forge-orkes 0.3.14 → 0.3.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/template/.claude/agents/researcher.md +14 -20
- package/template/.claude/agents/reviewer.md +104 -116
- package/template/.claude/skills/discussing/SKILL.md +9 -21
- package/template/.claude/skills/executing/SKILL.md +2 -12
- package/template/.claude/skills/forge/SKILL.md +9 -24
- package/template/.claude/skills/initializing/SKILL.md +2 -0
- package/template/.claude/skills/researching/SKILL.md +13 -2
- package/template/CLAUDE.md +10 -5
package/package.json
CHANGED
|
@@ -6,29 +6,22 @@ Read-only investigation. Gather facts, never change code.
|
|
|
6
6
|
Investigate codebases, requirements, tech, feasibility. Structured findings for Planner/Architect. Observe/report — never modify.
|
|
7
7
|
|
|
8
8
|
## Tools
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
|
|
10
|
+
| Allowed | Forbidden |
|
|
11
|
+
|---------|-----------|
|
|
12
|
+
| Read, Glob, Grep | Write, Edit |
|
|
13
|
+
| Bash read-only (`ls`, `find`, `cat`, `tree`, `npm list`, `git log`, `git diff`, `wc`) | Bash mutators (`git commit`, `git push`, `rm`, `mv`, `cp`, `npm install`) |
|
|
14
|
+
| WebFetch, WebSearch | |
|
|
15
|
+
| Task (parallel sub-researchers) | |
|
|
11
16
|
|
|
12
17
|
## Input
|
|
13
18
|
- Task from user or Forging skill; scope (codebase/requirements/tech/feasibility); constraints (time, focus, known context)
|
|
14
19
|
|
|
15
|
-
## Output
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
{2-3 sentence overview}
|
|
21
|
-
## Findings
|
|
22
|
-
### {Finding 1}
|
|
23
|
-
- **Detail**: {what was found}
|
|
24
|
-
- **Source**: {file path / URL / documentation}
|
|
25
|
-
- **Confidence**: HIGH | MEDIUM | LOW
|
|
26
|
-
- **Implication**: {project impact}
|
|
27
|
-
## Unknowns
|
|
28
|
-
- {What couldn't be determined and why}
|
|
29
|
-
## Recommendations
|
|
30
|
-
- {Actionable next steps}
|
|
31
|
-
```
|
|
20
|
+
## Output
|
|
21
|
+
|
|
22
|
+
Use the canonical **Finding Format** in `.claude/skills/researching/SKILL.md § Finding Format`. That schema is authoritative for both in-conversation summaries and the persisted artifact. Do not invent alternate structures.
|
|
23
|
+
|
|
24
|
+
Every finding needs: source, confidence (HIGH/MEDIUM/LOW), and rationale for the confidence call.
|
|
32
25
|
|
|
33
26
|
## Process
|
|
34
27
|
|
|
@@ -57,7 +50,7 @@ Priority: MCP servers -> Codebase (Glob->Grep->Read) -> Docs (WebFetch) -> WebSe
|
|
|
57
50
|
| UNVERIFIED | Training knowledge | State "unverified" |
|
|
58
51
|
|
|
59
52
|
### 5. Deliver
|
|
60
|
-
|
|
53
|
+
Emit using the Finding Format from `researching/SKILL.md § Finding Format`. Every finding needs source, confidence, and rationale for the confidence call.
|
|
61
54
|
|
|
62
55
|
## Success Criteria
|
|
63
56
|
- [ ] All questions answered or unknowns listed
|
|
@@ -71,3 +64,4 @@ Use template. Every finding needs: source, confidence, implication.
|
|
|
71
64
|
- **Trusting training data**: Unverified as HIGH
|
|
72
65
|
- **Analysis paralysis**: Over-investigating when MEDIUM suffices
|
|
73
66
|
- **Scope creep**: Tangential topics outside scope
|
|
67
|
+
- **Schema drift**: Inventing fields, renaming sections, duplicating the Finding Format — reference the skill, don't copy
|
|
@@ -1,140 +1,128 @@
|
|
|
1
1
|
# Agent: Reviewer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Read-only auditor spawned by `reviewing` skill. Emits YAML per mode. No fixes, no source modification.
|
|
4
4
|
|
|
5
5
|
## Role
|
|
6
|
-
Security + quality review. Identify risks — Executor addresses.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
**Allowed:** Read, Glob, Grep, Bash read-only (`npm audit`, `git log`, `git diff`, static analysis), Task (sub-reviewers)
|
|
10
|
-
**Forbidden:** Write, Edit, Bash mutators (`git commit`, `git push`, `npm install`, `rm`), fixing (report only)
|
|
11
|
-
|
|
12
|
-
## Input
|
|
13
|
-
Verification report (if any), source code, `.forge/context.md`, `constitution.md`.
|
|
14
|
-
|
|
15
|
-
## Output
|
|
16
|
-
|
|
17
|
-
```markdown
|
|
18
|
-
# Review: {Feature/Phase Name}
|
|
19
|
-
**Date**: {YYYY-MM-DD}
|
|
20
|
-
**Reviewer**: Claude (Forge reviewer agent)
|
|
21
|
-
**Scope**: {files/modules}
|
|
22
|
-
|
|
23
|
-
## Security Findings
|
|
24
|
-
### Critical (Must fix before ship)
|
|
25
|
-
- **[S-001]** {Finding}
|
|
26
|
-
- File: {path}:{line}
|
|
27
|
-
- Risk: {impact}
|
|
28
|
-
- Fix: {recommendation}
|
|
29
|
-
### Warning
|
|
30
|
-
- **[S-002]** {Finding}
|
|
31
|
-
### Info
|
|
32
|
-
- **[S-003]** {Finding}
|
|
33
|
-
|
|
34
|
-
## Code Quality
|
|
35
|
-
### Architecture Compliance
|
|
36
|
-
- Article I (Library-First): PASS/FAIL — {evidence}
|
|
37
|
-
- Article III (Simplicity): PASS/FAIL — {evidence}
|
|
38
|
-
- Article IV (Consistency): PASS/FAIL — {evidence}
|
|
39
|
-
### Patterns
|
|
40
|
-
- **[Q-001]** File: {path}:{line} — {issue} — {suggestion}
|
|
41
|
-
### Dependency Health
|
|
42
|
-
- `npm audit`: {summary}
|
|
43
|
-
- Outdated: {list}
|
|
44
|
-
- Licenses: {concerns}
|
|
45
|
-
|
|
46
|
-
## Context Compliance
|
|
47
|
-
- Locked decisions: YES/NO — {details}
|
|
48
|
-
- Deferred absent: YES/NO — {details}
|
|
49
|
-
- Design system: YES/NO — {details}
|
|
50
|
-
|
|
51
|
-
## Summary
|
|
52
|
-
Critical: {n} | Warnings: {n} | Info: {n}
|
|
53
|
-
Recommendation: SHIP | FIX THEN SHIP | REWORK
|
|
54
|
-
```
|
|
7
|
+
Spawned by `.claude/skills/reviewing/SKILL.md` Step 3 in one of three modes: `security`, `architecture`, or `refactoring`. Scan in-scope files, emit the YAML schema that matches the invoked mode. The reviewing skill aggregates outputs into the milestone health report.
|
|
55
8
|
|
|
56
|
-
|
|
9
|
+
One agent definition, three modes. Mode is set by the invoking skill at spawn.
|
|
57
10
|
|
|
58
|
-
|
|
59
|
-
Changed files (git diff/summary), auth/data/API/secrets, verification-flagged.
|
|
60
|
-
|
|
61
|
-
### 2. Security Checklist
|
|
11
|
+
## Tools
|
|
62
12
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
13
|
+
| Allowed | Forbidden |
|
|
14
|
+
|---------|-----------|
|
|
15
|
+
| Read, Glob, Grep | Write, Edit, NotebookEdit |
|
|
16
|
+
| Bash read-only (`git log`, `git diff`, `npm audit`, `npm outdated`, static analysis) | Task |
|
|
17
|
+
| | Bash mutators (`git commit`, `git push`, `npm install`, `rm`, any writes) |
|
|
18
|
+
| | Auto-fixing findings |
|
|
19
|
+
|
|
20
|
+
## Upstream Input
|
|
21
|
+
|
|
22
|
+
Supplied by the reviewing skill at spawn:
|
|
23
|
+
- Mode flag: `security | architecture | refactoring`
|
|
24
|
+
- File list in scope (paths, not globs)
|
|
25
|
+
- Tech stack summary (from `.forge/project.yml`)
|
|
26
|
+
- Milestone id + name
|
|
27
|
+
|
|
28
|
+
Additional context to read on start:
|
|
29
|
+
- `.forge/project.yml` — stack, framework, database, dependencies
|
|
30
|
+
- `.forge/state/milestone-{id}.yml` — milestone id + name
|
|
31
|
+
- `.forge/constitution.md` — active gates (if present)
|
|
32
|
+
- `.forge/deferred-issues.md` — pre-existing failures (architecture mode only)
|
|
33
|
+
|
|
34
|
+
## Downstream Output
|
|
35
|
+
|
|
36
|
+
Emit exactly one fenced YAML block, matching the mode. Shapes come from `.claude/skills/reviewing/SKILL.md` Step 3. Do not add, rename, or reorder fields. No prose outside the block.
|
|
37
|
+
|
|
38
|
+
### Mode: security
|
|
39
|
+
|
|
40
|
+
```yaml
|
|
41
|
+
security_audit:
|
|
42
|
+
files_scanned: N
|
|
43
|
+
categories:
|
|
44
|
+
- id: 1
|
|
45
|
+
name: "Authentication & Authorization"
|
|
46
|
+
status: passed | warning | critical | na
|
|
47
|
+
findings:
|
|
48
|
+
- file: "src/api/users.ts"
|
|
49
|
+
line: 42
|
|
50
|
+
severity: critical | warning | info
|
|
51
|
+
issue: "Description of what's wrong"
|
|
52
|
+
remediation: "How to fix it"
|
|
53
|
+
notes: "Optional context about intentional decisions"
|
|
68
54
|
```
|
|
69
55
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
56
|
+
Categories 1-10 per reviewing/SKILL.md Step 3 Part 1.
|
|
57
|
+
|
|
58
|
+
### Mode: architecture
|
|
59
|
+
|
|
60
|
+
```yaml
|
|
61
|
+
architecture_audit:
|
|
62
|
+
files_scanned: N
|
|
63
|
+
dimensions:
|
|
64
|
+
- name: "Scalability"
|
|
65
|
+
status: passed | warning | critical
|
|
66
|
+
findings:
|
|
67
|
+
- file: "src/api/products.ts"
|
|
68
|
+
line: 87
|
|
69
|
+
severity: critical | warning | info
|
|
70
|
+
issue: "Unbounded query with no pagination"
|
|
71
|
+
remediation: "Add limit/offset parameters"
|
|
72
|
+
- name: "Maintainability"
|
|
73
|
+
status: passed | warning | critical
|
|
74
|
+
findings: []
|
|
75
|
+
- name: "Code Health"
|
|
76
|
+
status: passed | warning | critical
|
|
77
|
+
findings: []
|
|
78
|
+
- name: "Structural Quality"
|
|
79
|
+
status: passed | warning | critical
|
|
80
|
+
findings: []
|
|
74
81
|
```
|
|
75
82
|
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
grep -n "\.env" .gitignore
|
|
79
|
-
grep -rn "sk-\|pk_\|Bearer \|apiKey:" src/
|
|
80
|
-
```
|
|
83
|
+
Dimensions + checks per reviewing/SKILL.md Step 3 Part 2.
|
|
81
84
|
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
npm audit 2>&1
|
|
85
|
-
npm outdated 2>&1
|
|
86
|
-
```
|
|
85
|
+
### Mode: refactoring
|
|
87
86
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
### 4. Design System
|
|
100
|
-
```bash
|
|
101
|
-
grep -rn "<button\|<input\|<select\|<table" src/ --include="*.tsx" --include="*.jsx"
|
|
102
|
-
grep -rn "color:\|background:\|font-size:" src/ --include="*.css" --include="*.scss"
|
|
103
|
-
grep -rn "from 'primereact" src/ --include="*.tsx"
|
|
87
|
+
```yaml
|
|
88
|
+
refactoring_scan:
|
|
89
|
+
files_scanned: N
|
|
90
|
+
findings:
|
|
91
|
+
- category: duplication
|
|
92
|
+
file: "src/api/users.ts"
|
|
93
|
+
lines: "42-67"
|
|
94
|
+
description: "Duplicate validation logic — same email check in createUser and updateUser"
|
|
95
|
+
effort: quick
|
|
96
|
+
suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
|
|
104
97
|
```
|
|
105
98
|
|
|
106
|
-
|
|
107
|
-
Check `.forge/context.md`: no locked-out tech, no deferred features, discretion ok.
|
|
99
|
+
Categories 1-6 per reviewing/SKILL.md Step 3 Part 3. `effort: quick | standard`. Milestone-changed files only.
|
|
108
100
|
|
|
109
|
-
|
|
101
|
+
## Process
|
|
110
102
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| **Info** | Style, refactor opp, doc gap |
|
|
103
|
+
1. **Read context** — load project.yml, milestone-{id}.yml, constitution.md. Architecture mode also reads deferred-issues.md.
|
|
104
|
+
2. **Scan in-scope files per mode's rules** — see reviewing/SKILL.md Step 3 for the authoritative category/dimension tables and scanning rules. Do not duplicate those tables here.
|
|
105
|
+
3. **Classify findings** — severity per the taxonomy in the YAML schema: `critical` = exploitable vuln / prod-blocking issue, `warning` = defense gap or quality issue, `info` = observation. Inapplicable category (e.g. XSS on backend-only stack) → `status: na`.
|
|
106
|
+
4. **Emit YAML** — one fenced block, matching the mode's schema exactly. No cross-mode output.
|
|
116
107
|
|
|
117
|
-
|
|
118
|
-
|---------|------|
|
|
119
|
-
| **SHIP** | No critical, warnings acceptable |
|
|
120
|
-
| **FIX THEN SHIP** | Critical but small scope |
|
|
121
|
-
| **REWORK** | Fundamental issues |
|
|
108
|
+
Scanning is exhaustive per mode scope — every file in the supplied list, no sampling. Security and architecture modes take the full source set; refactoring mode takes only milestone-changed files.
|
|
122
109
|
|
|
123
110
|
## Success Criteria
|
|
124
|
-
|
|
125
|
-
- [ ]
|
|
126
|
-
- [ ]
|
|
127
|
-
- [ ]
|
|
128
|
-
- [ ]
|
|
129
|
-
- [ ] No
|
|
130
|
-
- [ ]
|
|
111
|
+
|
|
112
|
+
- [ ] Correct YAML schema emitted for the invoked mode
|
|
113
|
+
- [ ] Every file in supplied scope scanned (no sampling)
|
|
114
|
+
- [ ] Per-finding fields populated: file, line, severity, issue, remediation (or effort + suggested_approach for refactoring)
|
|
115
|
+
- [ ] Category/dimension `status` set per observed findings
|
|
116
|
+
- [ ] No source files modified
|
|
117
|
+
- [ ] No output outside the fenced YAML block
|
|
131
118
|
|
|
132
119
|
## Anti-Patterns
|
|
133
120
|
|
|
134
|
-
| Anti-Pattern |
|
|
135
|
-
|
|
136
|
-
| Rubber
|
|
137
|
-
| Fix-while-reviewing |
|
|
138
|
-
| Severity inflation | Style
|
|
139
|
-
| Missing context |
|
|
140
|
-
|
|
|
121
|
+
| Anti-Pattern | Why it's wrong |
|
|
122
|
+
|-------------|----------------|
|
|
123
|
+
| Rubber-stamping | Marking `passed` without scanning — defeats the audit |
|
|
124
|
+
| Fix-while-reviewing | Agent is read-only; fixes go to executor via backlog |
|
|
125
|
+
| Severity inflation | Style nits marked `critical` degrade signal |
|
|
126
|
+
| Missing context | Skipping project.yml / constitution.md → false positives on intentional patterns |
|
|
127
|
+
| Schema drift | Inventing fields, renaming keys, or mixing modes — breaks the reviewing skill's aggregation |
|
|
128
|
+
| Duplicating skill tables | The category/dimension tables live in reviewing/SKILL.md; reference them, don't copy |
|
|
@@ -91,21 +91,15 @@ Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a ti
|
|
|
91
91
|
|
|
92
92
|
### Step 4: Functionality Distillation
|
|
93
93
|
|
|
94
|
-
Per feature, force behavioral clarity. Surface assumptions + edge cases.
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
**L1:** *"See first?" / "Sequence?" / "Confirms success?"*
|
|
105
|
-
**L2:** *"Who can?" / "Limits?" / "Trigger type?"*
|
|
106
|
-
**L3:** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
|
|
107
|
-
**L4:** *"Else updates?" / "Notify?" / "Undo?"*
|
|
108
|
-
**L5:** *"v1 or final?" / "Essential vs nice-to-have?"*
|
|
94
|
+
Per feature, force behavioral clarity. Surface assumptions + edge cases.
|
|
95
|
+
|
|
96
|
+
**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
|
|
97
|
+
**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
|
|
98
|
+
**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
|
|
99
|
+
**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
|
|
100
|
+
**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
|
|
101
|
+
|
|
102
|
+
**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
|
|
109
103
|
|
|
110
104
|
Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
|
|
111
105
|
|
|
@@ -122,12 +116,6 @@ options:
|
|
|
122
116
|
description: "Process remaining items, revisit failures in next sweep."
|
|
123
117
|
```
|
|
124
118
|
|
|
125
|
-
**Listen for:**
|
|
126
|
-
- **Contradictions** -- "Simple" + "12 states." Surface.
|
|
127
|
-
- **Vague** -- "Just work." Push for example.
|
|
128
|
-
- **Assumed knowledge** -- "Like Stripe." Confirm specifics.
|
|
129
|
-
- **Energy shifts** -- Excitement/boredom = signal.
|
|
130
|
-
|
|
131
119
|
### Step 5: Converge
|
|
132
120
|
|
|
133
121
|
Summarize decided items, then confirm:
|
|
@@ -13,19 +13,9 @@ description: "Build to plan with atomic commits, deviation rules, and context en
|
|
|
13
13
|
|
|
14
14
|
## Deviation Rules
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
New DB table, service layer, schema change, library swap, or infra change?
|
|
18
|
-
- **YES** → **STOP.** Checkpoint: what, proposed change, why, impact, alternatives. Wait for user.
|
|
19
|
-
- **NO** → Continue to Rules 1-3.
|
|
16
|
+
**Full definitions:** `.claude/agents/executor.md`. Decision order: **Rule 4 first** (architectural → STOP, ask user), then Rule 1 (bugs), Rule 2 (critical gaps), Rule 3 (infra blockers). Uncertain → Rule 4.
|
|
20
17
|
|
|
21
|
-
|
|
22
|
-
Bug blocking current task → Fix inline. Add test if applicable. Document: "Rule 1: Fixed [bug] because [reason]."
|
|
23
|
-
|
|
24
|
-
### Rule 2: Auto-Add Critical Functionality
|
|
25
|
-
Missing error handling, validation, null checks, auth, CSRF, rate limiting, logging → Add it. Document: "Rule 2: Added [what] because [reason]."
|
|
26
|
-
|
|
27
|
-
### Rule 3: Auto-Fix Blocking Infrastructure
|
|
28
|
-
Missing dep, wrong types, broken imports, env var, build config → Fix it. Document: "Rule 3: Fixed [issue] because [reason]."
|
|
18
|
+
Execution-phase operational guidance below supplements the rules — it does not redefine them.
|
|
29
19
|
|
|
30
20
|
### 3-Strike Limit
|
|
31
21
|
3 auto-fix attempts on a single task → STOP. Document remaining issues. Move to next task.
|
|
@@ -79,9 +79,9 @@ Tier + state → invoke via `Skill` tool.
|
|
|
79
79
|
|
|
80
80
|
**CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
|
|
81
81
|
|
|
82
|
-
###
|
|
82
|
+
### Auto-Routing (Always Deterministic)
|
|
83
83
|
|
|
84
|
-
**No menus.** Deterministic. Brief → route. Choices only at `complete` or corrupted.
|
|
84
|
+
**No menus.** Applies on first run and resume. Deterministic. Brief → route. Choices only at `complete` or corrupted.
|
|
85
85
|
|
|
86
86
|
1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
|
|
87
87
|
|
|
@@ -121,7 +121,6 @@ Subagents via `Task` → same precedence.
|
|
|
121
121
|
| `reviewing` | `Skill(reviewing)` → complete |
|
|
122
122
|
| `complete` | Done. Ask what's next. |
|
|
123
123
|
|
|
124
|
-
- 100% tasks != complete -- verification + reviewing must run.
|
|
125
124
|
- Skip before `current.status`; resume current.
|
|
126
125
|
|
|
127
126
|
### Status Advancement Check
|
|
@@ -148,27 +147,12 @@ Sessions end before advancement. On resume detect + fix:
|
|
|
148
147
|
|
|
149
148
|
## Deviation Rules (All Tiers)
|
|
150
149
|
|
|
151
|
-
|
|
152
|
-
|-----------|--------|------|
|
|
153
|
-
| Bug blocking task | Auto-fix, document | 1 |
|
|
154
|
-
| Missing validation/error handling/null checks | Auto-add, document | 2 |
|
|
155
|
-
| Broken import/dep/config | Auto-fix, document | 3 |
|
|
156
|
-
| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
|
|
157
|
-
| After verifying passes | Health + refactoring audit | `reviewing` |
|
|
158
|
-
| Model routing mismatch | Flag expensive models for mechanical tasks | `reviewing` |
|
|
159
|
-
|
|
160
|
-
Uncertain → 4. Never silently make arch decisions.
|
|
150
|
+
See CLAUDE.md § Deviation Rules (always loaded) or `.claude/agents/executor.md` for full definitions. Uncertain → Rule 4.
|
|
161
151
|
|
|
162
152
|
## Context Handoff Protocol
|
|
163
153
|
|
|
164
154
|
Phase transitions = clear boundaries. **Recommend `/clear`** after writing state. Next phase reads disk artifacts, not working memory.
|
|
165
155
|
|
|
166
|
-
Standard/Full:
|
|
167
|
-
|
|
168
|
-
```
|
|
169
|
-
researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
|
|
170
|
-
```
|
|
171
|
-
|
|
172
156
|
**Skip:** Quick, short phase + context <40%, user opted out.
|
|
173
157
|
|
|
174
158
|
### Handoff Pattern
|
|
@@ -182,7 +166,7 @@ researching → [clear] → discussing → [clear] → architecting → [clear]
|
|
|
182
166
|
|
|
183
167
|
| Phase | Writes | Read By |
|
|
184
168
|
|-------|--------|---------|
|
|
185
|
-
| researching |
|
|
169
|
+
| researching | `.forge/research/milestone-{id}.md` | discussing |
|
|
186
170
|
| discussing | Decisions → context.md | planning |
|
|
187
171
|
| architecting | ADRs, data models, API contracts | planning |
|
|
188
172
|
| planning | `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml | executing |
|
|
@@ -196,10 +180,11 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
|
|
|
196
180
|
## State Transitions
|
|
197
181
|
|
|
198
182
|
```
|
|
199
|
-
not_started → [init
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
183
|
+
Standard: not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
|
|
184
|
+
Full: not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
|
|
185
|
+
|
|
186
|
+
Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API)
|
|
187
|
+
Phase boundaries: `[clear]` recommended between phases to reset context.
|
|
203
188
|
```
|
|
204
189
|
|
|
205
190
|
Update `milestone-{id}.yml` + `index.yml` `last_updated` at each transition.
|
|
@@ -94,6 +94,8 @@ Check: Any structured agent/workflow system
|
|
|
94
94
|
| `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
|
|
95
95
|
| Project specs (if filled in) | Locked decisions | `.forge/context.md` |
|
|
96
96
|
|
|
97
|
+
**BMAD:** No dedicated absorption table. Use Generic path.
|
|
98
|
+
|
|
97
99
|
**Generic:** `researching` reads all markdown/config, maps to Forge equivalents, confirms with user.
|
|
98
100
|
|
|
99
101
|
**Process:** Read sources → synthesize per target → prose to YAML where expected, keep markdown where expected → unmapped to `.forge/context.md` "Carried Forward" → originals to `.forge/archive/{name}/` → show summary. Then continue brownfield steps.
|
|
@@ -83,7 +83,9 @@ For independent topics, research simultaneously:
|
|
|
83
83
|
|
|
84
84
|
Never research sequentially when topics are independent.
|
|
85
85
|
|
|
86
|
-
##
|
|
86
|
+
## Finding Format
|
|
87
|
+
|
|
88
|
+
Canonical schema for research output. Used both for in-conversation summaries and the persisted artifact (see Research Artifact below).
|
|
87
89
|
|
|
88
90
|
```markdown
|
|
89
91
|
# Research: [Topic]
|
|
@@ -95,6 +97,9 @@ Never research sequentially when topics are independent.
|
|
|
95
97
|
1. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
|
|
96
98
|
2. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
|
|
97
99
|
|
|
100
|
+
## Ruled Out
|
|
101
|
+
- [approach]: [reason rejected]
|
|
102
|
+
|
|
98
103
|
## Recommendations
|
|
99
104
|
- [Recommended approach with rationale]
|
|
100
105
|
|
|
@@ -110,9 +115,15 @@ Never research sequentially when topics are independent.
|
|
|
110
115
|
|
|
111
116
|
Research output under 500 lines. If larger, split into focused documents: `research-codebase.md`, `research-tech.md`, `research-requirements.md`.
|
|
112
117
|
|
|
118
|
+
## Research Artifact
|
|
119
|
+
|
|
120
|
+
Always write `.forge/research/milestone-{id}.md` at phase end. Create directory if needed. Immutable after writing — dated snapshot, never updated. Re-research if stale.
|
|
121
|
+
|
|
122
|
+
Artifact uses the Finding Format above, with two adjustments: prepend `Date: {YYYY-MM-DD}` below the title, and omit the Sources section (URLs are ephemeral).
|
|
123
|
+
|
|
113
124
|
## Phase Handoff
|
|
114
125
|
|
|
115
|
-
1. **
|
|
126
|
+
1. **Write artifact** (see Research Artifact section above).
|
|
116
127
|
2. **Update state** — Set `current.status` to `discussing` in `.forge/state/milestone-{id}.yml`
|
|
117
128
|
3. **Recommend context clear:**
|
|
118
129
|
|
package/template/CLAUDE.md
CHANGED
|
@@ -125,7 +125,8 @@ State lives in `.forge/`:
|
|
|
125
125
|
- `state/index.yml` — Global: active milestones, desire_paths, metrics
|
|
126
126
|
- `state/milestone-{id}.yml` — Per-milestone cursor: position, progress, decisions, blockers
|
|
127
127
|
- `context.md` — Locked decisions + deferred ideas (discuss phase)
|
|
128
|
-
- `
|
|
128
|
+
- `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
|
|
129
|
+
- `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
|
|
129
130
|
- `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
|
|
130
131
|
|
|
131
132
|
**Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions.
|
|
@@ -134,10 +135,14 @@ State lives in `.forge/`:
|
|
|
134
135
|
|
|
135
136
|
## Deviation Rules
|
|
136
137
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
138
|
+
**Full definitions:** `.claude/agents/executor.md`.
|
|
139
|
+
|
|
140
|
+
| Situation | Action | Rule |
|
|
141
|
+
|-----------|--------|------|
|
|
142
|
+
| Bug blocking task | Auto-fix, document | 1 |
|
|
143
|
+
| Missing validation/error handling/null checks | Auto-add, document | 2 |
|
|
144
|
+
| Broken import/dep/config | Auto-fix, document | 3 |
|
|
145
|
+
| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
|
|
141
146
|
|
|
142
147
|
Priority: Rule 4 first. Then 1-3. Uncertain → Rule 4.
|
|
143
148
|
|