You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: improve accuracy and clarity of documentation
- Rewrite how-it-works.md to focus on context window problem and Ralph loop
- Fix ralph-loop.md: replace mermaid with ASCII, correct chief-complete signal
- Credit snarktank/ralph and Geoffrey Huntley in README and docs
- Remove non-existent features: --prd flag, --dangerously-skip-permissions,
environment variables, exit codes 2/3, settings object in prd.json
- Change --prd to positional argument throughout docs
- Update git considerations with private vs shared options
- Reduce emdash usage throughout
Copy file name to clipboardExpand all lines: docs/concepts/chief-directory.md
+33-17Lines changed: 33 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ The root `.chief/` directory contains a single `prds/` subdirectory. Each PRD ge
30
30
Every PRD lives in its own named folder under `.chief/prds/`. The folder name is what you pass to Chief when running a specific PRD:
31
31
32
32
```bash
33
-
chief --prd my-feature
33
+
chief my-feature
34
34
```
35
35
36
36
Chief uses this folder as the working context for the entire run. All reads and writes happen within this folder — the PRD state, progress log, and Claude output are all scoped to the specific PRD being executed.
@@ -161,37 +161,53 @@ A single project can have multiple PRDs, each tracking a separate feature or ini
161
161
Run a specific PRD by name:
162
162
163
163
```bash
164
-
chief --prd auth-system
165
-
chief --prd payment-integration
164
+
chief auth-system
165
+
chief payment-integration
166
166
```
167
167
168
168
Each PRD tracks its own stories, progress, and logs independently. You can run them sequentially or work on different PRDs over time as your project evolves.
169
169
170
170
## Git Considerations
171
171
172
-
### What to Commit
172
+
You have two options depending on whether you want to share Chief state with your team.
173
173
174
-
| File | Commit? | Why |
175
-
|------|---------|-----|
176
-
|`prd.md`|**Yes**| Your requirements — the source of truth for what to build |
177
-
|`prd.json`|**Yes**| Story state and progress — lets collaborators see what's done |
178
-
|`progress.md`|**Yes**| Implementation history and learnings — valuable project context |
174
+
### Option 1: Keep It Private
179
175
180
-
### What to Ignore
176
+
If Chief is just for your personal workflow, ignore the entire directory:
181
177
182
-
| File | Ignore? | Why |
183
-
|------|---------|-----|
184
-
|`claude.log`|**Yes**| Large, regenerated each run, contains raw debug output |
178
+
```gitignore
179
+
# In your repo's .gitignore
180
+
.chief/
181
+
```
182
+
183
+
Or add it to your global gitignore to keep it private across all projects without modifying each repo:
If you want collaborators to see progress and continue where you left off, commit everything except the log files:
187
199
188
200
```gitignore
201
+
# In your repo's .gitignore
189
202
.chief/prds/*/claude.log
190
203
```
191
204
192
-
::: tip
193
-
Committing `prd.json` and `progress.md` means your team can see exactly which stories are complete and what was learned during implementation. This is especially useful when multiple people are contributing to the same project.
194
-
:::
205
+
This shares:
206
+
-`prd.md`: Your requirements, the source of truth for what to build
207
+
-`prd.json`: Story state and progress, so collaborators see what's done
208
+
-`progress.md`: Implementation history and learnings, valuable project context
209
+
210
+
The `claude.log` files are large, regenerated each run, and only useful for debugging.
description: Learn how Chief works as an autonomous PRD agent, transforming product requirements into working code through the Ralph Loop execution model.
2
+
description: Learn how Chief works as an autonomous coding agent, transforming your requirements into working code through an automated execution loop.
3
3
---
4
4
5
5
# How Chief Works
6
6
7
-
Chief is an autonomous PRD agent that transforms your product requirements into working code—without constant back-and-forth prompting.
7
+
Chief is an autonomous coding agent that transforms your requirements into working code, without constant back-and-forth prompting.
8
8
9
9
::: tip Background
10
10
For the motivation behind Chief and a deeper exploration of autonomous coding agents, read the blog post: [Introducing Chief: Autonomous PRD Agent](https://minicodemonkey.com/blog/2025/chief)
11
11
:::
12
12
13
13
## The Core Concept
14
14
15
-
Traditional AI coding assistants require constant interaction. You prompt, Claude responds, you prompt again. It's collaborative, but it's not autonomous.
15
+
Traditional AI coding assistants hit a wall: the context window. As your conversation grows, the AI loses track of earlier details, makes contradictory decisions, or simply runs out of space. Long coding sessions become unwieldy.
16
16
17
-
Chief takes a different approach: **define what you want upfront, then step back and watch it happen.**
17
+
Chief takes a different approach using a [Ralph Wiggum loop](https://ghuntley.com/ralph/): **each iteration starts fresh, but nothing is forgotten.**
18
18
19
-
You write a Product Requirements Document (PRD) describing what you want to build, broken into user stories. Chief reads the PRD, invokes Claude Code, and orchestrates the entire process—one story at a time.
19
+
You describe what you want to build as a series of user stories. Chief works through them one at a time, spawning a new Claude session for each. Between iterations, Chief persists state to a `progress.md` file: what was built, which files changed, patterns discovered, and context for future work. The next iteration loads this history, giving Claude everything it needs without the baggage of a bloated conversation.
20
20
21
-
## The Flow
21
+
Running `chief` opens a TUI dashboard where you can review your project, then press `s` to start the loop.
|**You**| Write the PRD with user stories and acceptance criteria |
35
-
|**PRD**| Machine-readable spec that defines what needs to be built |
36
-
|**Chief**| Orchestrator that manages the loop and tracks progress |
37
-
|**Claude**| AI agent that reads context, writes code, runs tests, and commits |
38
-
|**Code**| The end result—working code committed to your repository |
25
+
Chief works through your stories methodically. Each iteration focuses on a single story:
39
26
40
-
## One Iteration, One Story
27
+
```
28
+
┌───────────────────────────────────────┐
29
+
│ │
30
+
▼ │
31
+
┌──────────────┐ │
32
+
│ Pick Story │ │
33
+
│ (next todo) │ │
34
+
└──────┬───────┘ │
35
+
│ │
36
+
▼ │
37
+
┌──────────────┐ │
38
+
│ Invoke Claude│ │
39
+
│ with prompt │ │
40
+
└──────┬───────┘ │
41
+
│ │
42
+
▼ │
43
+
┌──────────────┐ │
44
+
│ Claude │ │
45
+
│ codes & tests│ │
46
+
└──────┬───────┘ │
47
+
│ │
48
+
▼ │
49
+
┌──────────────┐ │
50
+
│ Commit │ │
51
+
│ changes │ │
52
+
└──────┬───────┘ │
53
+
│ │
54
+
▼ │
55
+
┌──────────────┐ more stories │
56
+
│ Mark Complete├────────────────────────────────┘
57
+
└──────┬───────┘
58
+
│ all done
59
+
▼
60
+
✓ Finished
61
+
```
41
62
42
-
Chief works through your PRD methodically. Each "iteration" focuses on a single user story:
63
+
Here's what happens in each step:
43
64
44
-
1.**Read State** — Chief examines `prd.json` to find the highest-priority story where `passes: false`
45
-
2.**Build Prompt** — Constructs a prompt with instructions, the story details, and project context
46
-
3.**Invoke Claude** — Spawns Claude Code with the assembled prompt
47
-
4.**Execute** — Claude reads files, writes code, runs tests, and fixes issues until the story is complete
48
-
5.**Commit** — Claude commits the changes with a conventional commit message like `feat: [US-001] - Feature Title`
49
-
6.**Update PRD** — Marks the story as `passes: true` and records progress
50
-
7.**Repeat** — Chief checks for more incomplete stories and continues
65
+
1.**Pick Story**: Chief finds the highest-priority incomplete story
66
+
2.**Invoke Claude**: Constructs a prompt with the story details and project context, then spawns Claude Code
67
+
3.**Claude Codes**: Claude reads files, writes code, runs tests, and fixes issues until the story is complete
68
+
4.**Commit**: Claude commits the changes with a message like `feat: [US-001] - Feature Title`
69
+
5.**Mark Complete**: Chief updates the project state and records progress
70
+
6.**Repeat**: If more stories remain, the loop continues
51
71
52
72
This isolation is intentional. If something breaks, you know exactly which story caused it. Each commit represents one complete feature.
53
73
@@ -63,31 +83,28 @@ feat: [US-003] - Add user authentication
63
83
- Created auth middleware
64
84
```
65
85
66
-
Your git history becomes a timeline of features, matching 1:1 with your PRD stories.
86
+
Your git history becomes a timeline of features, matching 1:1 with your stories.
67
87
68
88
## Progress Tracking
69
89
70
-
Chief maintains a `progress.md` file in each PRD directory. After every iteration, Claude appends:
90
+
The `progress.md` file is what makes fresh context windows possible. After every iteration, Claude appends:
71
91
72
92
- What was implemented
73
93
- Which files changed
74
94
- Learnings for future iterations (patterns discovered, gotchas, context)
75
95
76
-
This creates institutional memory. Later iterations (and future developers) can reference this to understand decisions and avoid repeating mistakes.
77
-
78
-
## Why This Works
96
+
When the next iteration starts, Claude reads this file and immediately understands the project's history, without needing thousands of tokens of prior conversation. This gives you the benefits of long-running context (consistency, institutional memory) without the downsides (context overflow, degraded performance).
79
97
80
-
The autonomous approach enables things that interactive prompting can't:
98
+
## Staying in Control
81
99
82
-
-**Background execution** — SSH into a server, run `chief`, disconnect. Come back to finished features.
0 commit comments