ecokg/claude-forge-skill

Forge Skill v4

Autonomous execution engine. Any request → research → plan → execute → deliver. Base: ~/.claude/skills/forge/

Thinking Framework (Always Active)

Design thinking: First Principles (decompose to root cause) · Systems Thinking (trace ripple effects across modules) · Design Thinking (empathize → define → ideate → prototype → test) · Divide & Conquer (split into independently verifiable units)

Execution thinking: OODA Loop (observe → orient → decide → act, per task) · PDCA Cycle (plan → do → check → act, per phase) · 5 Whys (dig to root cause on failure) · Theory of Constraints (find bottleneck, focus resources there)

Discipline: Understand before acting. Verify — never assume. Change incrementally, validate each step. Maintain whole-plan context. Self-question: "Does this break existing functionality?" · "Is this the simplest solution?" · If complex, state why simple won't work.

Interaction Rule

ALWAYS use AskUserQuestion with selectable options when asking the user anything. Never ask open-ended text questions. Provide concrete choices so the user can select instead of typing. This applies to all confirmations, decisions, and clarifications throughout the entire forge flow.

Command Format

/forge "issue description" [options]

| Option | Values | Default | Description | |---|---|---|---| | --type | code/docs/analysis/infra/design | auto | Request type | | --direct | flag | off | Skip research+plan, PM designs tasks directly | | --no-research | flag | off | Skip research phase | | --from | filepath | — | Start from existing research.md or plan.md | | --model | opus/sonnet/haiku | auto | Force model for all stages | | --review | 0–5 | 1 | Number of plan reviewers | | --scale | auto/small/medium/large | auto | Task scale | | --phases | number | auto | Phase count override | | --exec | auto/subagent/team | auto | Execution strategy | | --lang | ko/en/… | auto | Output language (auto-detect from input) | | --cost | low/medium/high | medium | Cost tier | | --resume | slug | — | Resume interrupted artifact | | --init | flag | off | Project initialization mode |

No issue → ask user. --from plan.md → skip to Step 4. --from research.md → skip to Step 3.

Language Detection

If --lang not set, detect language from user's issue text. All user-facing output uses detected language. Skill internals, code, and variable names remain English.

Request Type Auto-Classification

| Type | Trigger keywords | Flow | Agents (from prompts/) | |---|---|---|---| | code | bug, fix, implement, refactor, feature | research→plan→implement→review→QA | implementer + code-reviewer + qa-inspector | | docs | document, write, translate, README | research→write→doc-review | implementer + doc-reviewer | | analysis | analyze, audit, profile, inspect | research→report (no implement) | analyst | | infra | deploy, CI/CD, config, environment | research→plan→execute (dry-run) | implementer | | design | architecture, schema, API design | research→design-doc→review | analyst (implement optional) |

Scale Detection (--scale auto)

| Scale | Files | Phases | Tasks | Research depth | |---|---|---|---|---| | small | 1–3 | 1 | 3–8 | 1–2 Explore | | medium | 4–10 | 2–3 | 8–20 | 2–4 Explore | | large | 10+ | 3–5 | 20+ | 3–5 Explore |

small → suggest --direct. Exec recommendation: small/medium → subagent, large → team.

Model Selection

Default (--cost medium)

| Stage | Model | Override with | |---|---|---| | File exploration | haiku | — | | Research/plan writing | sonnet | --model | | Plan review | haiku | — | | Implement (simple) | sonnet | --model | | Implement (complex/core) | opus | --model | | Code review | sonnet | --model | | Code review (phase-final) | opus | — | | QA verification | sonnet | --model |

--cost low → all haiku, skip review+QA. --cost high → all opus. Adaptive: 3+ consecutive PASS → downgrade review to haiku. Same-file edits → review last only.

Required Steps by Type — MANDATORY

Every /forge invocation MUST follow this table. No steps may be skipped unless explicitly marked.

| Step | code | docs | analysis | infra | design | |---|---|---|---|---|---| | 1. Init + Artifact | MUST | MUST | MUST | MUST | MUST | | 2. Research | MUST | MUST | MUST | MUST | MUST | | 3. Plan | MUST | skip | skip | MUST | MUST | | 4. Checkpoint | MUST | skip | skip | MUST | MUST | | 5. Git Branch | MUST | optional | skip | optional | optional | | 6. Tasks | MUST | MUST | skip | MUST | skip | | 7. Agent Setup | MUST | MUST | MUST | MUST | MUST | | 8. Execute | MUST | MUST | report only | MUST | report only | | 9. Finalize | MUST | MUST | MUST | MUST | MUST |

NEVER output analysis results as plain text. ALL output goes through artifacts (research.md/plan.md/report.md).

Execution Flow

Step 1: Parse + Detect + Initialize — MANDATORY FOR ALL TYPES

1. Extract issue (ask if missing)
2. Detect language, request type, scale
3. Recommend exec strategy → AskUserQuestion if --exec auto
4. Read templates/output.md for progress output formats — use throughout session
5. Read project-level rules if exists (.claude/forge-rules.md in project root)
6. Detect project language/framework → cache in .claude/project-profile.json
7. Generate slug + timestamp → create .claude/artifacts/{date}/{slug}-{HHMM}/ → init meta.json + update index.json (with path field)

HARD RULE: Artifact directory MUST exist before any research or analysis begins.

Step 2: Research — skip if --direct / --no-research / --from

1. Read templates/research.md for output structure
2. Check existing artifacts for same-module research (index.json) → reuse as baseline if recent (<30 days)
3. Spawn Explore agents (haiku) — count per scale table
4. Synthesize research.md (sonnet) with discovery IDs: H1, H2, M1, M2, L1…
5. Verify: Glob/Grep referenced files exist → fix stale references
6. Save to artifact dir → copy to project root
7. Update meta.json checkpoint: "step": "research_done"

Step 3: Plan — skip if --direct / --from plan.md

1. Read templates/plan.md for output structure
2. Write plan (sonnet): [N-M] task IDs + [REF:Hx,Mx] traceability tags
3. Save to artifact dir → copy to project root
4. Traceability: all HIGH refs covered? No phantom refs?
5. Review (haiku × --review): roles from pool R1–R5. PASS(≥7) / NEEDS_REVISION(5–6) / FAIL(≤4)
6. Auto-fix on revision → re-save → re-copy
7. Update checkpoint: "step": "plan_done"

Step 4: Checkpoint — skip if --direct

AskUserQuestion (single_select): "Execute" / "Revise then execute" / "Cancel" Cancel → meta.json status "cancelled", exit. Revise → collect feedback → modify plan → re-checkpoint.

Step 5: Git Branch

Suggest feature/{slug} branch. Skip if already on feature branch or user declines.

Step 6: Checklist → Tasks

• Parse - [ ] items → TaskCreate with [N-M] ID prefix
• --direct mode: PM analyzes issue, designs tasks directly, writes minimal plan.md
• Set Phase dependencies: Phase N first task blocked by Phase N-1 last task

Step 7: Agent Setup — Read prompts at spawn time

Load from prompts/ + checklists/:

• code: implementer.md + code-reviewer.md + qa-inspector.md + general.md + {detected-lang}.md
• docs: implementer.md + doc-reviewer.md
• analysis: analyst.md only
• infra/design: as mapped above

team mode: TeamCreate + spawn persistent agents with full prompts. subagent mode: Skip — agents spawned per-task in Step 8.

Step 8: PM Execution Loop

FOR EACH task (unblocked, ID ascending):
  1. Implementer: assign task (Agent call or SendMessage)
  2. GATE: self-check 6 items present + build pass → reject if incomplete
  3. PM structural check: plan coverage, file completeness
  4. Reviewer: code-reviewer / doc-reviewer / skip (analysis)
  5. Verdict: PASS → complete | NEEDS_REVISION → loop | REJECT → reimpl loop
  6. Phase end → QA → git commit "feat({slug}): complete phase {N}"
  7. Phase boundary report: continue / revise / stop (AskUserQuestion)
  8. meta.json real-time update

Context efficiency: Pass diff + surrounding context (not full file), current phase section (not full plan), task result summary (not full output) to agents. Limits: minor revisions ≤5, major ≤3, reject ≤2, QA retries ≤2 → AskUserQuestion escalation. Timeouts (team): implement 10m, review 5m, QA 5m → respawn 1× → escalation. Safety: DB/config/security/API/dependency changes → user confirmation before execution. Parallel: Independent same-Phase tasks run simultaneously (subagent: parallel Agent calls). Tasks modifying the same file(s) MUST run sequentially. Adaptive: 3+ revisions → suggest model upgrade. Frequent subagent revisions → suggest team switch.

Step 9: Finalize — MANDATORY FOR ALL TYPES

1. Shutdown agents (team: shutdown → 30s → TeamDelete)
2. Update plan.md: - [ ] → - [x] → re-copy to root (skip if no plan)
3. meta.json: status "completed", final stats verification
4. Read templates/report.md → generate final report → save to artifact dir + project root
5. Suggest PR creation (code/infra only)
6. Optional feedback → .claude/artifacts/{date}/{slug}-{HHMM}/feedback.md
7. Learning: if pattern detected 3+ times in revisions → append to .claude/forge-rules.md in project root

HARD RULE: Every /forge run MUST produce at minimum: meta.json + research.md + report.md in artifact dir.

Resume (--resume slug)

Read meta.json → verify "in_progress" → resume from checkpoint step. Restore exec_strategy.

Init (--init)

New project: ask tech stack → scaffold structure. Existing: analyze → generate project-profile.json.

Task ID System

Format: N-M (Phase-Task). Supplementary: N-Ma, N-Mb. Used in TaskCreate subject, progress output, meta.json checkpoint, agent communication.

Artifact Structure

.claude/artifacts/{date}/{slug}-{HHMM}/ → research.md, plan.md, meta.json, feedback.md(opt)

• Date: YYYY-MM-DD (creation date)
• Slug: a-z0-9 + hyphens, max 30 chars
• HHMM: creation time in 24h format (e.g., 1430)
• index.json: stores slug, path ({date}/{slug}-{HHMM}), created (YYYY-MM-DDTHH:MM)
• Artifact = master, root = one-way copy.