@khanhspring/forge-spec 1.0.0

package/bin/install.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { cpSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const SKILLS_DIR = join(homedir(), '.claude', 'skills');
+
+const SKILLS = [
+  'forge-brainstorm',
+  'forge-close',
+  'forge-config',
+  'forge-contract',
+  'forge-init',
+  'forge-spec',
+  'forge-status',
+  'forge-tasks',
+];
+
+console.log('Installing @forge-workflow/spec skills...\n');
+
+mkdirSync(SKILLS_DIR, { recursive: true });
+
+for (const skill of SKILLS) {
+  cpSync(join(ROOT, skill), join(SKILLS_DIR, skill), { recursive: true, force: true });
+  console.log(`  ✓ ${skill}`);
+}
+
+console.log(`\nInstalled to ${SKILLS_DIR}`);
+console.log('Restart Claude Code, then run /forge-init in your spec repo.');

package/forge-brainstorm/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: "forge-brainstorm"
+description: "Phase 1 of 4. Interrogates a feature idea through structured questioning, a challenge round, and 2–3 design approaches before writing a gated summary. Proactively researches existing context and surfaces research-blocked items before writing the spec."
+argument-hint: "Feature idea to brainstorm (e.g. 'user notifications')"
+compatibility: "Requires spec repo with .forge/project.json"
+metadata:
+  author: "forge-workflow"
+  source: "spec-skills/forge-brainstorm/SKILL.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Forge Brainstorm
+
+Phase 1 of 4. Your job is to fully understand a feature before any spec is written.
+The goal is zero ambiguity — every concern surfaced, every edge case accounted for,
+every unknown either resolved or explicitly accepted as an assumption.
+
+<HARD-GATE>
+Do NOT generate a spec, break down tasks, or write any contracts in this phase.
+The ONLY file this skill writes is `features/{slug}/brainstorm.md`, and only AFTER
+the user has explicitly approved the Brainstorm Summary at the gate (Step 7).
+"Simple" features are where unexamined assumptions cause the most wasted work — no feature
+skips this phase.
+</HARD-GATE>
+
+---
+
+## Step 1 — Load & Research Context
+
+Before asking the user anything, research the existing codebase silently:
+
+1. Read `.forge/project.json` — note module names, types, stacks, ports.
+2. Scan `features/*/spec.md` — are there related or similar features already specced?
+   Note any patterns, naming conventions, or prior decisions relevant to this idea.
+3. Scan `contracts/*/` — are there existing API contracts this feature will touch or extend?
+   Note existing endpoint shapes, error formats, auth patterns.
+4. Read `CLAUDE.md` — note project principles, conventions, and forbidden patterns
+   that will constrain design choices.
+
+Report your findings before starting questions:
+
+> "Before we dive in, here's what I found in the codebase:
+> - [relevant existing feature or contract, or "No related features found"]
+> - [relevant principle from CLAUDE.md, or "No constraints found"]
+>
+> I'll use this as context. Here's my understanding of the feature: {1–2 sentence restatement}
+> Is that right?"
+
+Then check scope:
+
+> If the idea spans multiple unrelated concerns: "This sounds like 2–3 separate features.
+> Shall we split and brainstorm each one, or treat it as a single feature?"
+
+---
+
+## Step 2 — Mandatory questions (one at a time)
+
+These MUST all be answered before moving to Step 4. Ask one at a time.
+Skip any sub-question already answered by your research in Step 1.
+
+**If a question hits an unknown** — something the user can't answer without researching —
+use the Research Flag pattern (see Research Handling below).
+
+**1. Problem & users**
+- What specific pain does this solve?
+- Who experiences it, and how often?
+- What happens today without this feature?
+
+**2. Actors & permissions**
+- Who are the actors? (end user / admin / system / external service)
+- Does each actor have different access levels or see different data?
+- Is any part restricted by role or ownership? (e.g. "users can only edit their own records")
+
+**3. Happy path**
+- Walk through the exact steps from trigger to completion.
+- What does the user see/receive at the end?
+
+**4. Data & state**
+- What data is created, read, updated, or deleted?
+- What persists after the action completes?
+- Is any of this shared with or derived from other modules?
+
+**5. Failure cases** — ask explicitly about each:
+- Invalid or missing input → what happens?
+- The same request submitted twice (idempotency)?
+- A downstream service or dependency is unavailable?
+- The user doesn't have permission?
+- Partial failure mid-flow — is rollback needed?
+
+**6. Modules & APIs**
+- Which modules are involved?
+- Does this extend existing APIs or is it net-new?
+- Does anything need to be deprecated or changed?
+
+---
+
+## Step 3 — Conditional questions (ask if not already answered)
+
+- **Integrations** — emails, push notifications, webhooks, third-party APIs?
+- **Async / background work** — any deferred or eventually consistent parts?
+- **Scale & performance** — volume expectations or SLA requirements?
+- **Consistency** — similar existing feature to follow for patterns?
+
+Skip any that are clearly irrelevant.
+
+---
+
+## Research Handling
+
+Use this pattern whenever a question surfaces something that cannot be answered
+through discussion alone.
+
+### When the user doesn't know the answer
+
+> "🔍 **Research needed:** {what needs to be found out}
+>
+> To answer this, you'd need to: {specific action — e.g. 'check if Stripe supports partial
+> refunds in your plan', 'ask the product team what the UX should be', 'look at how
+> user-service currently handles token expiry'}
+>
+> How do you want to proceed?
+> **(a) Pause here** — I'll give you a research checklist and we resume when you have answers
+> **(b) Proceed with an assumption** — I'll state an explicit assumption and flag it for validation
+> **(c) Keep going** — we'll leave this as an open question and resolve it before writing the spec"
+
+### When Claude can research it
+
+If the answer can be found by reading existing files in the repo:
+
+> "🔍 Let me check the existing codebase for this — one moment."
+
+Read the relevant file(s), then report what you found and whether it resolves the question.
+
+### Research pause
+
+If the user chooses **(a) Pause**:
+
+Output a research checklist:
+
+```
+⏸ Brainstorm paused — research needed before continuing.
+
+Research checklist:
+  □ {item 1} — {where to look / who to ask}
+  □ {item 2} — {where to look / who to ask}
+
+Resume by coming back and saying: "forge-brainstorm {slug} — resuming with answers:
+  - {item 1}: [your answer]
+  - {item 2}: [your answer]"
+```
+
+Stop here. Do not continue the brainstorm until the user resumes with answers.
+
+### Proceed with assumption
+
+If the user chooses **(b) Assumption**:
+
+State it explicitly and add it to the Assumptions section in the summary:
+
+> "✅ Assumption recorded: {clear statement of what we're assuming}
+> This will need validation before or during implementation."
+
+---
+
+## Step 4 — Challenge round
+
+Actively probe for hidden problems. Raise at least 2 concerns specific to the answers given:
+
+> "Before I propose approaches, I want to flag a couple of things:
+>
+> **[Concern 1]:** {specific concern from the conversation}
+>
+> **[Concern 2]:** {specific concern from the conversation}
+>
+> How should these be handled?"
+
+Wait for resolution before moving on. If a concern can't be resolved without research,
+apply the Research Handling pattern.
+
+---
+
+## Step 5 — Propose approaches
+
+Propose **2–3 design approaches** with trade-offs. Base them on the researched context
+from Step 1 — flag if an approach conflicts with existing patterns or CLAUDE.md principles.
+
+```
+I see 2–3 ways to approach this:
+
+**Option A (Recommended): {name}**
+{1–2 sentences}
+✓ {pro}  ✗ {con}
+{note if consistent/inconsistent with existing patterns}
+
+**Option B: {name}**
+{1–2 sentences}
+✓ {pro}  ✗ {con}
+
+**Option C: {name}** (if relevant)
+{1–2 sentences}
+✓ {pro}  ✗ {con}
+
+I'd go with Option A because {reason}. What do you think?
+```
+
+After the user picks, ask one follow-up:
+> "What's the main risk you see with this approach? Anything that makes you hesitant?"
+
+Resolve concerns before moving on.
+
+---
+
+## Step 6 — Synthesize
+
+Write the brainstorm summary in the conversation (no file):
+
+```
+## Brainstorm Summary: {Feature Name}
+**Slug:** {kebab-case-slug}
+**Approach:** {chosen option name}
+
+### Problem
+{1–2 sentences}
+
+### Actors & Permissions
+- **{Role}**: {what they do and what they can access}
+
+### Happy Path
+1. {step}
+2. {step}
+
+### Data & State
+- {what is created/read/updated/deleted}
+- {what persists and where}
+
+### Edge Cases & Failures
+- **{case}**: {handling}
+
+### Constraints
+- {constraint — or "None identified"}
+
+### Modules Involved
+- **{module-name}** ({type}): {responsibility in this feature}
+
+### Out of Scope
+- {explicitly excluded items}
+
+### Assumptions
+- {assumption}: {what it means if this is wrong}
+- (empty if no assumptions were made)
+
+### Research Needed
+- {item}: {what to check and where}
+- (empty if nothing is pending)
+
+### Open Questions
+- {unresolved concern — must be empty or moved to Research Needed before spec is written}
+```
+
+**Self-review before presenting:**
+- Any requirement readable two ways → pick one interpretation, state it explicitly
+- Any happy path step with no failure case → add it
+- Any "nice to have" → move to Out of Scope
+- Any contradiction between sections → resolve it
+- Anything in Open Questions that's actually a research item → move it to Research Needed
+- Open Questions not truly empty → do not write "None"
+
+Do not mention the self-review to the user.
+
+---
+
+## Step 7 — Gate
+
+Check all three blocking sections before accepting "yes":
+
+**If Open Questions is not empty:**
+> "Let's resolve these before writing the spec:
+> - {question}
+> How would you handle each?"
+Do NOT proceed until resolved.
+
+**If Research Needed is not empty:**
+> "There are items that need research before the spec can be finalized:
+> - {item}: {where to look}
+>
+> Do you want to:
+> **(a) Pause and research first** — I'll give you the checklist
+> **(b) Proceed and treat these as assumptions** — I'll add them to the spec as risks to validate"
+
+Wait for the user's choice. If (a), output the research checklist and stop.
+If (b), convert each item to an explicit assumption in the summary.
+
+**If Assumptions is not empty, warn:**
+> "Note: this spec will include {n} assumption(s) that need validation:
+> - {assumption}: {risk if wrong}"
+
+**Once all three sections are resolved or accepted:**
+> "Does this capture the feature correctly? Clarify anything above, or say **yes** to save it and move to the spec."
+
+---
+
+## Step 8 — Persist the summary (after approval only)
+
+Once the user says **yes**, write the approved summary to `features/{slug}/brainstorm.md`
+so it survives across sessions and forge-spec can pick it up later.
+
+```markdown
+# Brainstorm: {Feature Name}
+
+**Slug:** {slug}
+**Approach:** {chosen option name}
+**Captured:** {YYYY-MM-DD}
+
+{the full Brainstorm Summary body from Step 6 — all sections}
+```
+
+Then hand off:
+> "Saved to `features/{slug}/brainstorm.md`. Run `/forge-spec {slug}` to write the spec."
+
+---
+
+## Rules
+- One question per message — never list multiple at once
+- Prefer multiple-choice when options are predictable
+- Never skip Step 2 mandatory areas — even for "simple" features
+- Never skip the challenge round (Step 4)
+- Never skip the approaches step (Step 5)
+- YAGNI: move anything non-core to Out of Scope
+- The ONLY file written is `features/{slug}/brainstorm.md`, and only after approval (Step 8)
+- Do NOT skip Step 1 research — always check existing context first
+- Do NOT ask questions that could be answered by reading the existing codebase

package/forge-close/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: "forge-close"
+description: "Marks a module's tasks as done in features/{slug}/tasks.md, generates the spec repo commit message, and checks whether all modules have completed — closing the feature if so."
+argument-hint: "Feature slug and module name (e.g. 'user-registration user-service')"
+compatibility: "Requires spec repo with .forge/project.json and features/{slug}/tasks.md"
+metadata:
+  author: "forge-workflow"
+  source: "spec-skills/forge-close/SKILL.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Forge Close — Spec Repo
+
+Mark a module's implementation tasks as done in the spec repo.
+Run this after `/forge-done` in the module repo.
+
+---
+
+## Pre-check
+
+- Read `.forge/project.json` — get module list.
+  If missing: "Run `/forge-init` to set up this spec repo first."
+- Parse $ARGUMENTS:
+  - First word → feature slug
+  - Second word → module name
+  - If slug missing → ask: "Which feature are you closing?"
+  - If module missing → ask: "Which module are you marking as done?
+    _(Available modules: {list from project.json})_"
+- Read `features/{slug}/tasks.md` — must exist.
+  If missing: "No tasks file found. Run `/forge-tasks {slug}` first."
+- Validate module name exists in `### {module}` section of tasks.md.
+  If not found: "No tasks for `{module}` in `{slug}`. Check the module name matches exactly."
+
+---
+
+## Step 1 — Show current task state
+
+Display the module's current tasks:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Closing: {module} / {feature-slug}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+- [ ] TASK-1 [api] POST /users/register endpoint
+- [ ] TASK-2 [feat] Password hashing + validation
+- [x] TASK-3 [test] Unit tests for UserService
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If all tasks are already ticked:
+> "All tasks for `{module}` are already marked done. Nothing to update."
+Check overall feature status (Step 3) and stop.
+
+Otherwise ask:
+> "Mark all {n} tasks for `{module}` as done? Say **yes** to update, or tell me which ones to skip."
+
+Wait for confirmation before writing.
+
+---
+
+## Step 2 — Update tasks.md
+
+In `features/{slug}/tasks.md`, tick all confirmed tasks under `### {module}`:
+- Change `- [ ]` → `- [x]` for each confirmed task
+- Leave any explicitly skipped tasks untouched
+- Update the `**Last updated:**` date at the top of the file to today
+
+Show a diff summary:
+```
+Updated features/{slug}/tasks.md:
+- [x] TASK-1 [api] POST /users/register endpoint  ← ticked
+- [x] TASK-2 [feat] Password hashing + validation  ← ticked
+- [x] TASK-3 [test] Unit tests for UserService  (was already done)
+```
+
+---
+
+## Step 3 — Check overall feature completion
+
+Scan ALL `### {module}` sections in `tasks.md`.
+Count ticked vs unticked tasks per module:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Feature progress: {feature-slug}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+- [x] user-service — 3/3 tasks done
+- [ ] web-app — 0/2 tasks done
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If all modules are complete:**
+Update `features/{slug}/tasks.md` header status to `Done`
+and `features/{slug}/spec.md` header status to `Done`.
+
+> "🎉 All modules done — feature `{slug}` is complete."
+
+**If modules still remain:**
+
+List what's left:
+> "{module} still has {n} task(s) remaining.
+> Once they run `/forge-done {slug}` in their module repo,
+> they can run `/forge-close {slug} {module}` here to close out."
+
+---
+
+## Step 4 — Generate commit message
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Commit message
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+chore(tasks): mark {module} done for {feature-slug}
+
+Completed tasks:
+- TASK-1: {title}
+- TASK-2: {title}
+- TASK-3: {title}
+
+{if all modules done}
+Feature {feature-slug} fully implemented across all modules.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then remind:
+> "After committing and pushing, module repos should run:
+> `git submodule update --remote specs`
+> to sync the updated task status."

package/forge-config/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "forge-config"
+description: "View and interactively update .forge/project.json: add or remove modules, update ports, change stack info, or update the spec repo URL. Asks one question at a time and previews changes before writing."
+argument-hint: "Optional hint: 'add module', 'update user-service port', 'remove web-app'"
+compatibility: "Requires spec repo with .forge/project.json"
+metadata:
+  author: "forge-workflow"
+  source: "spec-skills/forge-config/SKILL.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Forge Config
+
+View and update the project configuration at `.forge/project.json`.
+
+## Step 1 — Load & display
+
+Read `.forge/project.json`.
+If missing: "No project config found. Run `/forge-init` to set up this repo first."
+
+Display the current config:
+
+```
+Project: {project-name}
+Spec repo: {spec_repo}
+Contract tool: {contract_tool}
+
+Modules ({n}):
+  · user-service    backend   Spring Boot 3, Java 21   :8081
+  · web-app         frontend  React, TypeScript         :3000
+```
+
+## Step 2 — Determine the change
+
+From $ARGUMENTS, infer the intent if given (e.g. "add module", "update user-service port").
+If empty, ask: "What do you want to change? (add a module / remove a module / update a field / change spec repo URL)"
+
+## Step 3 — Collect details (one question at a time)
+
+Ask one question per message — never batch.
+
+**Adding a module** — ask in order, one at a time:
+1. "Module name? (kebab-case, must be unique)"
+2. "Type? (backend / frontend / worker / gateway)"
+3. "Tech stack? (e.g. 'Spring Boot 3, Java 21')"
+4. "Local dev port?"
+5. "Git repo URL? (or 'none')"
+6. "One-sentence description? (or 'none')"
+
+**Removing a module:**
+- Check whether any `features/*/tasks.md` has a `### {module}` section.
+  If so, warn: "`{module}` has tasks in {feature(s)}. Removing it from config won't delete those tasks. Remove anyway? (yes/no)"
+- Otherwise confirm: "Remove `{module}` from the project? (yes/no)"
+
+**Updating a field:**
+- Show the current value, then ask for the new one:
+  "`{module}.{field}` is currently `{old}`. What should it be?"
+
+**Changing spec repo URL:**
+- "Current spec_repo is `{old}`. New URL?"
+
+## Step 4 — Preview & gate
+
+Show the before/after of exactly what will change:
+
+```
+Change preview:
+  modules[user-service].port:  8081  →  8090
+```
+
+> "Apply this change to `.forge/project.json`? Say **yes** to write, or tell me what to adjust."
+
+Wait for confirmation. Do not write before the user says yes.
+
+## Step 5 — Write & confirm
+
+Apply the change, preserving all other fields and formatting.
+Confirm: "Updated `.forge/project.json` — {summary of what changed}."
+
+If a module name changed, warn:
+> "Heads up: `{module}` is referenced by the module repo's `.forge/module.json` and by
+> `### {module}` headings in tasks.md. Update those to match, or `/forge-implement` and
+> `/forge-close` will break."
+
+## Schema Reference
+
+```jsonc
+{
+  "project": "my-project",        // short slug, no spaces
+  "version": "1.0",
+  "modules": [
+    {
+      "name": "user-service",     // kebab-case, matches module.json in module repos
+      "repo": "git@github.com:org/user-service.git",
+      "type": "backend",          // backend | frontend | worker | gateway
+      "stack": ["Spring Boot 3", "Java 21"],
+      "port": 8081,
+      "description": ""           // optional, one sentence
+    }
+  ],
+  "spec_repo": "git@github.com:org/specs.git",
+  "contract_format": "openapi3",
+  "contract_tool": "specmatic"
+}
+```
+
+## Rules
+- One question per message — never batch
+- Never write before the user confirms the preview in Step 4
+- `module.name` must be kebab-case and unique
+- `module.name` must match the `module` field in the module repo's `.forge/module.json`
+- Never silently remove a module that has tasks referencing it — warn first