The Problem

Developers who want to use Claude Code for large, multi‑step projects must manually split work, keep track of progress, and re‑seed the model after each commit. The process is error‑prone and hard to automate, especially when the Claude context window is exceeded.

What This Does

chief automates that workflow. A PRD (product‑requirements‑document) lives under .chief/prds/… and is loaded by internal/prd/loader.go. The CLI (cmd/chief/main.go) launches a Bubble Tea TUI (internal/tui/app.go) that drives a “Ralph Wiggum” loop (internal/loop/manager.go / internal/loop/loop.go). Each loop iteration spawns Claude Code via a subprocess, writes the generated code to the repo, and records the step in the PRD. The UI shows progress panels (render* functions) and lets the user start, pause, or abort the loop.

How It Is Wired

  1. Entry point – main in cmd/chief/main.go (line 33) parses flags and calls runTUIWithOptions.
  2. runTUIWithOptions → IsGitRepo (subprocess via cmd.Run) → validates the working directory.
  3. It then invokes LoadPRD (internal/prd/loader.go) which reads the JSON/MD files from .chief/prds/.
  4. A new TUI app is created: NewApp in internal/tui/app.go (calls NewManager → NewLoop in internal/loop/loop.go).
  5. The manager starts the loop (Run → NewLoop → NewManager). Run is the most‑called function (30 distinct callers).
  6. Inside the loop, render* functions (e.g., renderEmptyPRDPanel, renderErrorPanel) are invoked from 36 places, handling all UI updates.
  7. The loop’s core work is Run → NewLoop → runClaudeConversion (internal/prd/generator.go) which spawns Claude Code (exec.Command).
  8. After each successful generation, Save (internal/prd/loader.go) writes the updated PRD back to disk.

The call graph contains 580 internal edges; the hub functions (Render, Run, LoadPRD, ParseLine, NewManager) have the widest blast radius. No circular imports were detected, but internal/loop/manager.go and internal/loop/loop.go each have deep nesting (indentation depth 16) and duplicated 6‑line blocks across several files, making future changes risky.

How To Use It

# Clone and build
git clone https://github.com/moses-y/chief
cd chief
make            # builds the binary in ./bin/chief

Or install via the provided script:

curl -fsSL https://raw.githubusercontent.com/MiniCodeMonkey/chief/refs/heads/main/install.sh | sh

Prerequisites: the Claude Code CLI must be installed and authenticated (see README). No additional config files are required; the TUI creates .chief/prds/ on first run. Launch the UI:

./bin/chief          # starts the TUI

Create a new project:

./bin/chief new      # invokes internal/cmd/new.go → runInteractiveClaude

The UI responds to s to start the loop, q to quit, and other keys documented in internal/tui/help.go.

Real‑World Use

A front‑end team wants to scaffold a marketing site. They run chief new, answer the initial prompts, and let the loop generate component files, commit after each task, and update the PRD automatically. The CI pipeline can later run go test ./... to verify the generated code before release.

Code Health & Issues

  • High – Pin GitHub Actions to commit SHAs (.github/workflows/*.yml).
  • High – No LICENSE file (rights undefined).
  • High – CI workflow does not execute the test suite.
  • Medium – No Dependabot/Renovate configuration.
  • Medium – No dependency‑vulnerability scan in CI.
  • Medium – Checkout step keeps token (persist-credentials: false needed).
  • Low – Jobs lack timeout-minutes.
  • High – Deep nesting in cmd/chief/main.go and internal/loop/manager.go.
  • High – Duplicated code blocks across UI components and command files.
  • Medium – Oversized file internal/tui/app.go (828 LOC).
  • Medium – High branching density in several command files.

The Bottom Line

chief delivers a concrete automation layer for Claude Code, with a functional TUI and clear PRD workflow. However, the codebase suffers from high cognitive load, duplicated logic, and several SDLC gaps (missing license, incomplete CI). It is usable for experimentation but would need refactoring and CI hardening before production adoption.