@firatcand/forge 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@firatcand/forge",
+  "version": "0.1.0",
+  "description": "A lightweight framework for shipping software products from idea to production with AI coding agents (Claude Code, Codex CLI, Cursor, Gemini)",
+  "type": "module",
+  "bin": {
+    "forge": "bin/forge.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "agents/",
+    "templates/",
+    "ETHOS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "codex",
+    "cursor",
+    "gemini",
+    "ai-agent",
+    "agentic-coding",
+    "framework",
+    "skills",
+    "subagents",
+    "compound-engineering",
+    "product-development",
+    "linear",
+    "github"
+  ],
+  "author": "Firat Can Basarir",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firatcand/forge.git"
+  },
+  "homepage": "https://github.com/firatcand/forge#readme",
+  "bugs": {
+    "url": "https://github.com/firatcand/forge/issues"
+  }
+}

package/skills/codex/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: codex
+description: Get a second opinion from Codex CLI on the current diff or specific files. Required for changes touching CRITICAL.md paths.
+tools: Bash(codex*), Bash(git*), Read
+---
+
+# /codex
+
+## Preconditions
+
+- Codex CLI installed (`which codex`)
+- Active Codex membership (handled by Codex CLI's own auth)
+
+## Modes
+
+### review (default)
+
+```bash
+git diff HEAD | codex --stdin
+```
+
+### adversarial
+
+```bash
+codex --adversarial --diff
+```
+
+Prompts Codex to actively try to find ways to break the code.
+
+### consult
+
+```bash
+codex consult --file [path]
+```
+
+Open a session with Codex on a specific file or topic.
+
+## When to use
+
+- Always for files matching paths in CRITICAL.md
+- Architecture decisions
+- Anything where you'd want a second engineer to look at it
+
+## Integration with /ship
+
+If `/ship` detects the diff touches CRITICAL.md paths, it runs `/codex review` automatically and blocks PR creation if critical findings.
+
+## Output
+
+Codex CLI's review output, formatted for readability. Findings categorized by severity.

package/skills/decompose/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: decompose
+description: Break the validated spec into phases.yaml — a dependency graph of tasks across Phase 1/2/3 with gate criteria, owner types, and acceptance criteria.
+tools: Read, Write, Edit
+subagent: product-decomposer
+---
+
+# /decompose
+
+Delegate to the `product-decomposer` subagent.
+
+## Preconditions
+
+`spec/CONTEXT.md` must exist.
+
+## Algorithm
+
+1. Identify the smallest end-to-end working slice → Phase 1
+   - Phase 1 goal is always: "skeleton works end-to-end with mock/seed data"
+2. Identify the core feature loops → Phase 2
+   - Phase 2 goal: "real users can complete the primary JTBD"
+3. Identify polish + launch prep → Phase 3
+   - Phase 3 goal: "quality bar for public launch"
+
+## Per-task fields
+
+- id (P{phase}-T{nn})
+- title (verb + noun, max 8 words)
+- description (1 paragraph)
+- type (foundation | data | backend | frontend | design | infra | content | integration)
+- priority (P0 | P1 | P2)
+- depends_on (list of task IDs)
+- estimate (S | M | L | XL)
+- owner_type (which subagent picks this up)
+- acceptance_criteria (concrete, testable)
+
+## Hard rules
+
+- No XL tasks ship — split them
+- Every phase has explicit gate_criteria
+- Dependency graph must be a DAG (validator catches cycles)
+
+## Refinement
+
+Show YAML to user, ask for one round of edits. Then write to `plans/phases.yaml`.
+
+Print: "phases.yaml written. /push-to-linear unlocked. Gate 4 — review the breakdown."

package/skills/draft-design/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: draft-design
+description: Generate spec/DESIGN.md from spec/PRD.md. References user's brand-book and design-system via @inherit pattern.
+tools: Read, Write, Edit
+---
+
+# /draft-design
+
+## Preconditions
+
+- `spec/PRD.md` must exist
+- User's brand assets configured in `~/.claude/CLAUDE.md` under `brand_assets`
+
+## Configuration expected
+
+```yaml
+# In ~/.claude/CLAUDE.md
+brand_assets:
+  brand_book: ~/work/brand/BRAND-BOOK.md
+  design_system: ~/work/brand/DESIGN-SYSTEM.md
+  voice_register: ~/work/brand/VOICE.md
+```
+
+If not configured, prompt user to set these once.
+
+## Orchestration
+
+1. Read PRD, brand_book, design_system, voice_register
+2. Check if user has a `ux-design` skill — invoke with all four as context
+3. Determine project surface area (marketing site, app UI, email, docs)
+4. Generate DESIGN.md using `@inherit` pattern — reference brand assets, don't duplicate
+
+## The @inherit pattern
+
+DESIGN.md should reference, not duplicate:
+
+```markdown
+## Tokens
+@inherit ~/work/brand/DESIGN-SYSTEM.md#tokens
+
+Project-specific overrides:
+- accent: --color-coral (use only for primary CTA)
+
+## Voice
+@inherit ~/work/brand/VOICE.md
+
+Project-specific calibration:
+- This is a tool, not editorial — trim lyricism, keep precision
+```
+
+When brand assets update, project DESIGN.md inherits the change.
+
+## Output
+
+`spec/DESIGN.md` + Gate 3 confirmation.

package/skills/draft-prd/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: draft-prd
+description: Generate spec/PRD.md from spec/BRIEF.md. Orchestrates the user's product-spec skill if available, otherwise guides Claude through the PRD template directly.
+tools: Read, Write, Edit
+---
+
+# /draft-prd
+
+## Preconditions
+
+`spec/BRIEF.md` must exist. If not, refuse and direct user to `/forge`.
+
+## Orchestration
+
+1. Read `spec/BRIEF.md`
+2. Check if user has a `product-spec` skill available globally — if yes, invoke it with BRIEF.md as input
+3. If not, use `templates/PRD.template.md` directly and guide Claude through filling each required section based on BRIEF
+4. Cross-check generated PRD against BRIEF — flag any drift (new features not in v1 scope, success metrics differing from BRIEF's north star)
+5. Write to `spec/PRD.md`
+
+## Required PRD sections
+
+- Problem (synthesized from BRIEF.pain, made concrete)
+- Target user (specific persona, JTBD format)
+- Acceptance Criteria (testable bullets)
+- Non-goals (must include all from BRIEF.non-goals)
+- Success metrics (must include north-star from BRIEF)
+- Constraints (budget, timeline, regulatory, integrations)
+
+## Output
+
+Print:
+
+```
+PRD written to spec/PRD.md
+
+Acceptance criteria preview:
+- [criterion 1]
+- [criterion 2]
+- [criterion 3]
+
+Gate 2 — review the PRD. To proceed:
+  • /draft-spec to generate the technical SPEC
+  • /draft-design to generate the DESIGN doc (if UI-heavy)
+  • Edit spec/PRD.md directly
+  • /draft-prd --refine [section] to re-generate a weak section
+```

package/skills/draft-spec/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: draft-spec
+description: Generate spec/SPEC.md from spec/PRD.md. Orchestrates the user's software-architect skill if available, otherwise guides Claude through the SPEC template.
+tools: Read, Write, Edit
+---
+
+# /draft-spec
+
+## Preconditions
+
+`spec/PRD.md` must exist (Gate 2 must have passed).
+
+## Orchestration
+
+1. Read `spec/PRD.md`
+2. Read `~/.claude/CLAUDE.md` for any stack_preferences block
+3. Check if user has a `software-architect` skill available — if yes, invoke it with PRD + stack preferences
+4. If not, use `templates/SPEC.template.md` and guide Claude through filling sections
+5. Invoke `security-auditor` subagent in advisory mode for the chosen stack — get security model recommendations
+6. Write to `spec/SPEC.md`
+
+## Required SPEC sections
+
+- Stack (runtime, frontend, backend, db, hosting, auth)
+- Data model (tables, relationships, indexes)
+- Key flows (numbered steps with edge cases)
+- Integration points (external services)
+- Security model (authN, authZ, sensitive data handling)
+- Environment variables (12-Factor compliant — names + descriptions)
+- Performance targets (p95 metrics)
+- Observability (logs, metrics, errors)
+
+## Stack choice ceremony
+
+If SPEC implies a tech stack not yet committed, invoke Confusion Protocol:
+- List 2-3 viable options
+- Show concrete trade-offs
+- Stop and ask user to pick before writing
+
+## Output
+
+Print confirmation + Gate 3 instructions.

package/skills/fix/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: fix
+description: Apply a fix based on /investigate output. Refuses to run without recent investigation.
+tools: Edit, Read, Bash(*)
+---
+
+# /fix
+
+## Preconditions
+
+`plans/tasks/{LINEAR-ID}.investigation.md` must exist and be < 24 hours old.
+
+## Process
+
+1. Read investigation
+2. Apply minimal fix matching root cause
+3. Add regression test that reproduces the original bug (Test-or-die)
+4. Verify fix + test passes
+5. Commit with conventional message: `fix(scope): brief description`
+
+## After 3 failed attempts
+
+Stop. Demand fresh `/investigate`. Do not thrash.

package/skills/forge/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: forge
+description: Apply Socratic pressure to a raw idea and produce a validated project BRIEF. Heavy ceremony — 6 forcing questions. The required first command for any new forge project.
+tools: Read, Write, Edit, Bash(git*)
+---
+
+# /forge
+
+Take a raw idea — a sentence in the user's head — and produce a validated `spec/BRIEF.md` that everything downstream draws from.
+
+## When invoked
+
+User runs `/forge` (no args) at the start of a new project, OR `/forge --refine [section]` to re-run on a weak section of an existing BRIEF.md.
+
+## The 6 Forcing Questions
+
+You MUST ask all six. Do not skip. Do not soften. Push back when answers are vague.
+
+### Q1 — The pain
+"What pain are we solving? Who feels it most acutely? When did you last see it felt? What do they do today instead?"
+
+If the answer is "people want X" — push back. People wanting is not pain. Demand a specific moment, a specific user, a specific workaround.
+
+### Q2 — The unfair advantage
+"Why you, and why now? What do you know, have access to, or have built before that gives you a meaningful edge?"
+
+If the user has none, push back: "If anyone could build this in a weekend, why hasn't it won?"
+
+### Q3 — The smallest valuable thing
+"What is the smallest version of this that would still be worth using? Strip everything optional. What remains?"
+
+If the answer includes "and also" more than twice, force a cut.
+
+### Q4 — The non-goals
+"What will you explicitly NOT build, even when asked? What's tempting but a trap?"
+
+If the user can't list non-goals, the scope will balloon.
+
+### Q5 — Success in one number
+"If this is wildly successful in 6 months, what single number proves it? Not a vanity metric."
+
+Push back on multi-metric answers. Force one.
+
+### Q6 — The kill criteria
+"What evidence in 4 weeks, 12 weeks, 6 months would mean 'stop'?"
+
+Most projects die because nobody set a kill line.
+
+## Adaptive depth
+
+If answers to Q1-Q3 are sharp, you may compress Q4-Q6 into a single combined question. You do not skip the questions, only their separation.
+
+If any answer is vague, ask up to 3 follow-ups before moving on.
+
+## Output
+
+Use `templates/BRIEF.template.md` to write `spec/BRIEF.md`.
+
+After writing, print:
+
+```
+BRIEF written to spec/BRIEF.md
+
+5-bullet summary:
+1. [problem]
+2. [user]
+3. [v1 scope]
+4. [north star]
+5. [kill criteria]
+
+Gate 1 — review the brief. To proceed:
+  • /draft-prd to generate the PRD
+  • Edit spec/BRIEF.md directly for fixes
+  • /forge --refine [section] to re-Socratic a weak section
+```
+
+## --refine mode
+
+When invoked with `--refine [section]`:
+1. Read existing spec/BRIEF.md
+2. Re-ask the relevant forcing questions with sharper framing
+3. Update only that section
+4. Show diff before writing
+
+## Confusion Protocol
+
+If the user's idea is too vague to even start the forcing questions, stop and ask for the one-sentence pitch first. Don't try to extract Q1 from "I want to build something."

package/skills/implement/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: implement
+description: Execute the approved plan from /plan-task. Refuses to run without an approved plan unless --quickfix flag.
+tools: Edit, Read, Write, Bash(*)
+---
+
+# /implement
+
+## Preconditions
+
+- `plans/tasks/{LINEAR-ID}.plan.md` exists and was committed
+- OR `--quickfix` flag with justification
+
+## Execution
+
+1. Read plan
+2. Execute step-by-step, committing after each logical unit
+3. Use conventional commit messages
+4. If you encounter a Confusion Protocol trigger not in the plan, STOP and ask
+5. Run `npm run typecheck` (or equivalent) after each major change
+
+## Output
+
+Summary of files changed, commits made, any deviations from plan.

package/skills/ingest-spec/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ingest-spec
+description: Validate that BRIEF, PRD, SPEC, and (optional) DESIGN are all complete and consistent. Build CONTEXT.md as canonical synthesis. Required before /decompose.
+tools: Read, Write
+---
+
+# /ingest-spec
+
+## Validation checklist
+
+For BRIEF.md:
+- [ ] Pain section is concrete (not "people want")
+- [ ] Target user is specific
+- [ ] Non-goals listed
+- [ ] North-star metric has a number
+
+For PRD.md:
+- [ ] Acceptance criteria are testable
+- [ ] Non-goals match BRIEF non-goals
+- [ ] Success metrics include BRIEF north-star
+
+For SPEC.md:
+- [ ] Stack is specified
+- [ ] Data model present
+- [ ] Env variables enumerated
+- [ ] Security model defined
+
+For DESIGN.md (if exists):
+- [ ] Tokens reference brand-book via @inherit OR are explicitly defined
+- [ ] Voice section calibrated for this product
+
+## Cross-document consistency
+
+- PRD acceptance criteria must be testable given SPEC's data model
+- DESIGN voice must be compatible with PRD's target user
+- All env vars in SPEC must have entries in `.env.example`
+
+## On failure
+
+List what's missing or inconsistent. Block /decompose.
+
+## On success
+
+Write `spec/CONTEXT.md` — single-page synthesis of all four docs. This is what `/decompose` reads.
+
+Print: "Spec validated. /decompose unlocked."

package/skills/investigate/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: investigate
+description: Iron Law of Investigation — required before /fix. Trace data flow, test hypotheses, identify root cause.
+tools: Read, Bash(*)
+---
+
+# /investigate
+
+## Process
+
+1. Reproduce the bug — write the minimal repro steps
+2. Identify the data flow involved
+3. Form hypothesis: "I think the bug is caused by X because Y"
+4. Test the hypothesis — instrument code, check logs, run debugger
+5. Either confirm or rule out; if ruled out, form next hypothesis
+6. Document the root cause: "Root cause: X. Evidence: Y. Affected paths: Z"
+
+## Output
+
+Write `plans/tasks/{LINEAR-ID}.investigation.md` with:
+- Repro steps
+- Hypotheses tested
+- Root cause identified
+- Proposed fix approach (high-level)
+
+This file is required by /fix.

package/skills/learn/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: learn
+description: Write a learning entry capturing what surprised us, what we'd do differently. Auto-suggested by /ship if task was notable.
+tools: Read, Write
+subagent: learning-curator
+---
+
+# /learn
+
+Delegate to `learning-curator`.
+
+## Triggers (any one makes the task "notable")
+
+- Investigation took > 30 min
+- > 2 fix attempts before success
+- Surprised by behaviour
+- Found a non-obvious gotcha
+- Made a non-trivial trade-off
+- Bootstrapped something new (test framework, CI, infrastructure)
+
+## Process
+
+1. Read the last commit + PR description + investigation file (if exists)
+2. Extract:
+   - What we expected
+   - What actually happened
+   - Why
+   - What we'd do differently
+3. Tag with relevant types
+4. Write 5-10 line learning to `docs/learnings/{quarter}/{slug}.md` using `templates/learning.template.md`
+
+## Format
+
+```markdown
+# {Slug title}
+> {ISO date} · {LINEAR-ID} · tags: [foundation, testing]
+
+## What we expected
+[1-2 lines]
+
+## What happened
+[2-3 lines]
+
+## Why
+[1-2 lines]
+
+## Next time
+[1-2 lines]
+```
+
+## Retrieval
+
+`/pickup-task` reads recent learnings tagged with the new task's type and injects them into context. The system gets smarter over time.

package/skills/phase-gate/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: phase-gate
+description: Ceremony to advance from phase N to phase N+1. Verifies gate criteria, runs end-to-end check, generates retro, prompts for human approval.
+tools: Read, Write, Bash(*)
+subagent: phase-gatekeeper
+---
+
+# /phase-gate
+
+Delegate to `phase-gatekeeper`.
+
+## Args
+
+- `phase-{N}` (e.g., `phase-1`)
+
+## Steps
+
+1. Read `plans/phases.yaml` for `phase-N.gate_criteria`
+2. Verify all phase-N tasks are Done in Linear (abort with list if not)
+3. Run `gate_check_command` from phases.yaml (e.g., `npm run e2e && npm run typecheck`)
+4. Generate `docs/retros/phase-{N}.md`:
+   - Tasks shipped (with PR links)
+   - Decisions made
+   - Scope changes from original phases.yaml
+   - Learnings to harvest
+   - What to do differently in phase-{N+1}
+5. Print summary, ask: "Approve advancing to phase-{N+1}? [y/N]"
+6. On `y`:
+   - Linear: close Cycle N, activate Cycle N+1
+   - Move all phase-(N+1) tasks Backlog → Todo
+   - Update phases.yaml: `phase-N.status = "complete"`
+   - Commit retro
+7. On `N`: list what's missing, exit (no partial advances)
+
+## Output
+
+If approved: confirmation + Phase N+1 task summary. If not: list of blockers.

package/skills/pickup-task/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: pickup-task
+description: Claim the next available task from Linear (or local phases.yaml), create a git worktree, and inject relevant learnings.
+tools: Read, Edit, Bash(git*), Bash(gh*)
+subagent: learning-curator
+---
+
+# /pickup-task
+
+## Args
+
+- `[phase]` — default: current active phase
+- `[type-filter]` — optional, filter by owner_type
+
+## Steps
+
+1. Query Linear (via MCP) for issues in current Cycle that are:
+   - Status: Todo
+   - All `blocked_by` issues are Done
+2. If multiple match, list and ask user to pick. If one, auto-pick.
+3. Set Linear issue status → "In Progress"
+4. Compute branch name: `feat/{LINEAR-ID}-{kebab-case-title}`
+5. Create git worktree:
+   ```bash
+   PROJECT_NAME=$(basename "$(pwd)")
+   WORKTREE_PATH="../${PROJECT_NAME}-worktrees/${LINEAR-ID}"
+   git worktree add "${WORKTREE_PATH}" -b "${BRANCH_NAME}" dev
+   ```
+6. Delegate to `learning-curator` to retrieve relevant learnings:
+   - Tags matching task type
+   - Created in last 90 days
+7. Output:
+
+```
+✓ Worktree created: ../my-project-worktrees/TLOG-101
+✓ Linear issue TLOG-101 → In Progress
+✓ Branch: feat/TLOG-101-bootstrap-nextjs
+
+Acceptance criteria:
+  - Email + Google OAuth working
+  - Migrations run cleanly
+  - Vercel preview deploy on PR
+
+Relevant learnings (3):
+  - 2026-Q2/nextjs-supabase-typegen.md
+  - 2026-Q2/vercel-env-vars-runtime.md
+  - 2026-Q1/git-hooks-prettier-conflict.md
+
+Next:
+  cd ../my-project-worktrees/TLOG-101
+  claude
+  > /plan-task
+```

package/skills/plan-task/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: plan-task
+description: Run Plan mode for the current task. Outputs structured plan; required before /implement.
+tools: Read, Write, Edit
+---
+
+# /plan-task
+
+## Steps
+
+1. Read Linear issue (or phases.yaml task) for current branch
+2. Determine task type → delegate to relevant specialist subagent (frontend-dev, backend-dev, db-architect, etc.)
+3. Specialist enters Plan mode: research codebase, propose approach
+4. Write structured plan to `plans/tasks/{LINEAR-ID}.plan.md`:
+   - Files to change (predicted)
+   - Component tree / data flow
+   - State / data flow
+   - Edge cases
+   - Test strategy
+   - Open questions (Confusion Protocol triggers)
+5. Show plan to user, wait for approval
+6. On approval: commit plan, unlock /implement