forge-builder
Skill0 starsChanged 9 months agoMITView on GitHub
Autonomous building/coding skill with self-review, self-improvement, and quality validation loops. Classifies input as directive (build) or inquiry (analyze). Can be used standalone or orchestrated by forge-orchestrator. Invoke with /forge-builder [task]. Do NOT use for research — use forge-research instead.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- auditing-skillsSkill
- creating-skillsSkill
- forge-claude-teamsSkill
- forge-codex-multiagentSkill
- forge-orchestratorSkill
- forge-researchSkill
- handoff-freshSkill
- handoffSkill
- managing-doc-manifestSkill
- okfSkill
- pickupSkill
- studySkill
- syncing-docsSkill
- testing-skillsSkill
- updating-skillsSkill
- wrapSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 20 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 40
Check for architect/ directory with plan artifacts
- Very specific: line 41
If found: verify freshness — "stale" means architect/ mtime is older than the most recent 3 commits, OR CLAUDE.md phase does not match …
- Distinctive: line 42
If stale or ambiguous: ask user — "Found architect/ from a previous iteration.
- Very specific: line 43
If no architect/: accept direct instructions or run a quick structuring pass
- Distinctive: line 77
Read CLAUDE.md and TODO.md if they exist.
- Very specific: line 97
If a plan already exists (orchestrated mode or architect/ directory), use it.
- Distinctive: line 102
Write the plan to TODO.md (or update existing TODO.md)
- Distinctive: line 104
Keep phases small. Each phase should produce a working, testable increment.
- Distinctive: line 125
Do the changes follow existing codebase conventions?
- Distinctive: line 130
If test infrastructure exists, run the relevant test suite.
- Distinctive: line 147
ALL must pass (see quality-gates.md for details):
- Distinctive: line 153
No regressions in existing functionality
- Distinctive: line 157
If the gate fails: fix the issues, re-run the gate.
- Distinctive: line 193
Write it using the format in suggestions-template.md
- Distinctive: line 197
Run the full test suite (if infrastructure exists)
- Distinctive: line 198
Verify all TODO.md items are completed or documented as deferred
- Very specific: line 222
Write ownership: Only the main builder thread (or orchestrator) writes agent-authored sections.
- Very specific: line 228
Rejected: update status to rejected, leave in file for reference.
- Distinctive: line 230
No feedback yet: leave as-is. Do NOT block waiting for feedback — continue with other work
- Distinctive: line 238
ALL must pass for a phase to be considered complete.
- Distinctive: line 258
Git checkpointing: commit after each completed milestone
- Distinctive: line 260
Test-first: when infrastructure exists, write/update tests before implementation
- Distinctive: line 261
Browser automation: use browser automation tools (if available) for UI testing — this "dramatically improved performance" (Anthropic)
- Distinctive: line 267
When forge-builder is orchestrated and multiple build agents run in parallel:
- Distinctive: line 273
If multiple agents defer changes to the same file, the orchestrator reconciles all deferred changes together
- Distinctive: line 288
Update this skill when:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Forge Builder
Autonomous building with self-review, self-improvement, and quality gates.
Entry Point
Two modes of invocation:
Orchestrated (from forge-orchestrator): Skip auto-detect. Use the provided plan directly. Do NOT ask the user anything — the orchestrator has already established the plan. Proceed to Step 1 with the plan as input.
Standalone (direct user invocation): Classify the request first:
- Directive (unambiguous action): "Build the auth module", "Add caching to the API" — proceed with build
- Inquiry (analysis/advice): "How should we handle auth?", "What's the best caching strategy?" — respond with analysis only, do NOT modify files until a follow-up directive is issued
This classification prevents auto-implementing when the user is still exploring options.
For directives, auto-detect input:
- Check for
architect/directory with plan artifacts - If found: verify freshness — "stale" means
architect/mtime is older than the most recent 3 commits, OR CLAUDE.md phase does not match TODO.md state - If stale or ambiguous: ask user — "Found architect/ from a previous iteration. Use it, start fresh, or describe what you want?"
- If no
architect/: accept direct instructions or run a quick structuring pass
Workflow
- [ ] 1. Parse build directive → produces: Goals/Constraints/Context extracted
- [ ] 2. Detect platform + read practices → produces: platform name logged
── GATE A: directive parsed + practices read ──
- [ ] 3. Plan implementation approach → produces: phased plan in TODO.md
── GATE B: plan visible before any code changes ──
- [ ] 4. Execute build phases → per-phase: implement → review → test → improve → gate
- [ ] 5. New feature detection → produces: SUGGESTIONS.md entries (if any)
- [ ] 6. Final validation → produces: completion summaryStep Completion Protocol
Every step must produce visible output before the next step begins. GATE markers are hard checkpoints.
- GATE A (after Steps 1-2): You must have extracted goals/constraints AND read the practices guide. If you haven't read the practices guide file, STOP and read it now.
- GATE B (after Step 3): You must have a phased plan (in TODO.md or output). If you are about to write code without a plan, STOP — even simple tasks benefit from a brief phase list.
Why gates matter: Without them, the natural tendency is to skip directly from reading the task to writing code, bypassing platform detection (which governs isolation and conflict prevention) and planning (which prevents rework). The build phases (Step 4) have their own quality gates already — the risk is in the pre-build steps.
Step 1: Parse Build Directive
You MUST extract and output these before proceeding:
- Goals: what must be built and what success looks like
- Constraints: technology, performance, compatibility requirements
- Codebase context: existing patterns, conventions, test infrastructure
Read CLAUDE.md and TODO.md if they exist. Use their conventions as binding constraints.
Step 2: Platform Detection
MANDATORY. Detect the agent platform and read the practices guide BEFORE writing any code.
| Signal | Platform | Action |
| Agent tool, TeamCreate, SendMessage, or EnterWorktree available | Claude Code | Read .claude/skills/forge-claude-teams/SKILL.md |
| spawn_agent, AGENTS.md, fork_context available | Codex CLI | Read .claude/skills/forge-codex-multiagent/SKILL.md |
| Neither detected | Fallback | Assume Claude Code, log warning: "Platform not detected, defaulting to Claude Code practices" |
You MUST read the practices guide file — it contains isolation methods, conflict prevention, and context handoff templates that govern how build agents are spawned. Log which platform was detected.
GATE A checkpoint: Do not proceed to Step 3 unless you have (1) extracted goals/constraints from Step 1 and (2) read the practices guide file. If you skipped either, go back now.
Step 3: Plan Implementation
MANDATORY. You must have a phased plan before writing any code — even for "simple" tasks. A brief 3-line phase list counts; no plan at all does not.
If a plan already exists (orchestrated mode or architect/ directory), use it. Otherwise:
- Break work into phases with clear milestones
- Identify file ownership boundaries per phase
- Define quality gates per milestone — what "done" means for each phase
- Write the plan to TODO.md (or update existing TODO.md)
Keep phases small. Each phase should produce a working, testable increment.
GATE B checkpoint: Do not proceed to Step 4 unless you have a phased plan (in TODO.md or output). If you are about to write code without any plan, STOP and create one now — even a 3-line phase list prevents rework.
Step 4: Execute Build Phases
For each phase, execute these sub-steps in order:
a. Implement
Write code changes. Sequential by default — parallelize only when phases are genuinely independent and own different files. If forge-build-worker is available (.claude/agents/forge-build-worker.md exists), spawn it for implementation in worktree isolation. Describe the end-state, not step-by-step procedure: "Build X that passes Y" is better than "First do A, then B, then C."
b. Self-Review (or Adversarial Review)
Self-review (default for standalone use): Structured review of own changes against requirements.
Adversarial review (when orchestrated or for critical builds): If forge-adversarial-reviewer is available (.claude/agents/forge-adversarial-reviewer.md exists), spawn it with the diff and requirements for independent critique. Fresh-context review catches issues self-review misses.
Structured review of own changes against requirements:
- Does this satisfy the phase goals?
- Are there logic errors or missed edge cases?
- Do the changes follow existing codebase conventions?
- Are there any security or data-loss risks?
c. Run Tests
If test infrastructure exists, run the relevant test suite. If no tests exist, skip this sub-step (do not fabricate test infrastructure unless the directive asks for it).
d. Self-Improvement Scan
Scan the code just written for actionable improvements:
- Performance: obvious inefficiencies, unnecessary allocations, O(n^2) in hot paths
- Quality: better patterns available, clearer naming, reduced duplication
- Error handling: missing edge cases at external boundaries (I/O, API calls, user input)
- Test coverage: untested paths in modified code
e. Implement Improvements
Apply improvements from the scan. Scope: existing functionality only. See Improvement vs New Feature Boundary for the decision table.
f. Quality Gate Check
ALL must pass (see quality-gates.md for details):
- Tests pass (if infrastructure exists)
- Lint/format clean (if configured)
- Self-review finds no critical issues
- Changes satisfy stated requirements
- No regressions in existing functionality
g. Gate Failure Protocol
If the gate fails: fix the issues, re-run the gate. Maximum 2 retries per phase. After the third failure, escalate to the user with:
- What failed
- What was tried
- Suggested next steps
h. Update Progress
Mark the phase complete in TODO.md. If using git checkpointing, commit after each passed gate.
Step 5: New Feature Detection
During implementation, you will discover potential features or enhancements not in the original plan. Classify each one:
Improvement vs New Feature Boundary
| Action | Classification | What to Do |
| Performance optimization of existing code | Improvement | Implement directly |
| Refactoring for clarity | Improvement | Implement directly |
| Error handling at existing boundaries | Improvement | Implement directly |
| Tests for existing untested code | Improvement | Implement directly |
| Fixing inconsistencies in existing patterns | Improvement | Implement directly |
| New user-facing behavior | New feature | Save to SUGGESTIONS.md |
| New API endpoints or commands | New feature | Save to SUGGESTIONS.md |
| New integrations | New feature | Save to SUGGESTIONS.md |
| New configuration options | New feature | Save to SUGGESTIONS.md |
| Significant architectural changes | New feature | Save to SUGGESTIONS.md |
When in doubt, save to SUGGESTIONS.md. The cost of suggesting something the user implements is far lower than the cost of implementing something the user rejects.
For each suggestion saved to SUGGESTIONS.md:
- Research the feature briefly
- Draft an implementation plan
- Assign a confidence score (1-5)
- Write it using the format in suggestions-template.md
Step 6: Final Validation
- Run the full test suite (if infrastructure exists)
- Verify all TODO.md items are completed or documented as deferred
- Generate a completion summary:
- What was built
- What was improved during self-improvement scans
- What was deferred to SUGGESTIONS.md
- Any remaining risks or open questions
SUGGESTIONS.md Format
SUGGESTIONS.md is a bidirectional async communication channel — the agent writes suggestions, the human writes feedback. This allows human steering of autonomous development without interrupting the workflow. See suggestions-template.md for the full template.
Status lifecycle:
- Agent creates suggestion:
proposed - Agent researches:
researched - Agent drafts plan:
planned - Agent self-reviews plan:
ready-for-review - Human writes decision in
### Human Feedback:approved— agent implements in next build cyclerejected— agent skips, leaves for referenceneeds-revision+ comments — agent refines, cycles back toplanned
- Agent implements approved suggestion:
implemented
Write ownership: Only the main builder thread (or orchestrator) writes agent-authored sections. The ### Human Feedback section is exclusively human-written — the agent reads it but never modifies it.
Processing Human Feedback
At every milestone boundary and during the COMPOUND step, re-read SUGGESTIONS.md and check for human feedback:
- Approved (
ready-for-revieworplannedwithapproveddecision): promote to a new milestone or add to the next milestone's scope - Rejected: update status to
rejected, leave in file for reference. Do not re-suggest unless the human explicitly revises their decision - Needs-revision: incorporate human comments into the plan, re-run self-review, update status back to
planned - No feedback yet: leave as-is. Do NOT block waiting for feedback — continue with other work
Quality Gate Criteria
"Validation is the only path to finality."
ALL must pass for a phase to be considered complete. See quality-gates.md for the full reference.
| Gate | Condition | Skip If |
| Tests | All pass | No test infrastructure |
| Lint/Format | Clean output | No linter configured |
| Self-Review | No critical issues (broken functionality, security vulnerabilities, data loss risks) | Never skip |
| Requirements | Changes match stated goals | Never skip |
| Regressions | No existing functionality broken | Never skip |
Gate failure: fix, re-gate (max 2 retries), escalate to user.
Long-Running Build Sessions
For builds spanning multiple milestones or exceeding context limits. See long-running.md for the full reference.
Key principles:
- Single-feature focus: one milestone or feature per build agent
- Git checkpointing: commit after each completed milestone
- Compaction-resilient state: persist state to FORGE-HANDOFF.md, TODO.md continuously
- Test-first: when infrastructure exists, write/update tests before implementation
- Browser automation: use browser automation tools (if available) for UI testing — this "dramatically improved performance" (Anthropic)
Conflict Prevention (Build-Specific)
When forge-builder is orchestrated and multiple build agents run in parallel:
- Each agent gets a structured FILE SCOPE declaration (own/read/deny) via context handoff
- Agents MUST NOT modify files outside their FILE SCOPE own list
- Out-of-scope changes needed: write to
DEFERRED-CHANGES.mdwith the file path, the change needed, and why - The orchestrator processes deferred changes after the current phase completes
- If multiple agents defer changes to the same file, the orchestrator reconciles all deferred changes together
DEFERRED-CHANGES.md format:
## {file path}
- **Agent**: {agent name}
- **Change needed**: {description}
- **Reason**: {why this is needed for the agent's scope to work}
- **Priority**: {blocking | enhancement}Self-Evolution
Update this skill when:
- Quality gate criteria change: new validation steps, new tools for automated checking
- Self-improvement patterns improve: better heuristics for the improvement vs new feature boundary
- Build workflow changes: new phases, reordered phases, or phases that should be skipped
- Platform API changes: new isolation mechanisms, new checkpointing features
Current version: 1.1.0. See CHANGELOG.md for history.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

