@khanhspring/forge-spec 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhspring/forge-spec",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Forge spec repo skills for Claude Code — brainstorm, spec, tasks, contract, and more",
   "type": "module",
   "bin": {

package/skills/forge-brainstorm/SKILL.md

@@ -61,14 +61,15 @@ Before asking the user anything, research the existing codebase silently:
    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.
+4. Read `CONTEXT.md` — note the actors, domain glossary, principles, conventions, and
+   forbidden patterns that will constrain design choices. Use glossary terms verbatim
+   in your questions and in the summary — never invent synonyms for existing domain terms.
 
 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"]
+> - [relevant principle or constraint from CONTEXT.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?"
@@ -210,7 +211,7 @@ 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.
+from Step 1 — flag if an approach conflicts with existing patterns or CONTEXT.md principles.
 
 ```
 I see 2–3 ways to approach this:

package/skills/forge-config/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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'"
+description: "View and interactively update .forge/project.json (add/remove modules and submodules, ports, stack, spec repo URL) and CONTEXT.md (actors, glossary, principles, conventions). Asks one question at a time and previews changes before writing."
+argument-hint: "Optional hint: 'add module', 'add submodule to webapps', 'update user-service port', 'edit principles'"
 compatibility: "Requires spec repo with .forge/project.json"
 metadata:
   author: "forge-workflow"
@@ -12,14 +12,16 @@ disable-model-invocation: true
 
 # Forge Config
 
-View and update the project configuration at `.forge/project.json`.
+View and update the project configuration at `.forge/project.json`, and the
+project-wide domain context at `CONTEXT.md`.
 
 ## 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:
+Display the current config. Modules with submodules show one indented `↳` row per
+submodule — the parent row has no port/stack (those belong to each submodule):
 
 ```
 Project: {project-name}
@@ -28,13 +30,19 @@ Contract tool: {contract_tool}
 
 Modules ({n}):
   · user-service    backend   Spring Boot 3, Java 21   :8081
-  · web-app         frontend  React, TypeScript         :3000
+  · webapps         (3 submodules)
+    ↳ admin         frontend  React                    :3001   apps/admin
+    ↳ landing       frontend  Next.js                  :3000   apps/landing
+    ↳ portal        frontend  React                    :3002   apps/portal
 ```
 
 ## 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)"
+From $ARGUMENTS, infer the intent if given (e.g. "add module", "add submodule to webapps",
+"update user-service port", "edit principles").
+If empty, ask: "What do you want to change? (add a module / add a submodule to an existing
+module / remove a module or submodule / update a field / change spec repo URL / edit project
+context — actors, glossary, principles, conventions)"
 
 ## Step 3 — Collect details (one question at a time)
 
@@ -44,22 +52,68 @@ Ask one question per message — never batch.
 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)"
+4. "Git repo URL? (or 'none')"
+5. "Does `{name}` contain multiple submodules — e.g. a monorepo with several apps,
+   or a Gradle multi-module build? (yes / no)"
+   - **If yes** → collect submodules one at a time (see below). Skip step 6 —
+     port and stack belong to each submodule, not the parent; drop the stack from step 3
+     if it was given for the parent.
+   - **If no** → continue.
+6. "Local dev port?" _(skip when the module has submodules)_
+7. "One-sentence description? (or 'none')"
+
+**Adding a submodule** (to an existing module) — ask which module first if not given.
+
+- If the parent is currently a **simple module** (no `submodules[]`), warn before converting:
+  > "`{module}` is currently a standalone module. Adding a submodule converts it:
+  > its `port` and `stack` move to the submodules — the parent keeps only `name`,
+  > `repo`, and `description`. If `{module}` already has tasks or contracts under its
+  > own name, those stay as-is and won't match a submodule name. Convert? (yes/no)"
+  If yes, ask whether the existing port/stack should become the first submodule
+  (asking for its `name` and `path`) or be discarded.
+- Then collect each new submodule, one field at a time (same as `/forge-init`):
+  1. "Submodule name? (kebab-case, unique across the whole project — not just within `{module}`)"
+  2. "Type? (backend / frontend / worker)"
+  3. "Stack?"
+  4. "Port?"
+  5. "Path within the `{module}` repo? (e.g. `apps/admin` or `auth-ui`)"
+  6. "One sentence: what does it do? _(Skip with 'none')_"
+- Confirm each: "`{sub}` — {type} — {stack} — :{port} — path: {path}. Another submodule? (yes / no)"
+
+> **Submodule rules (same as `/forge-init`):**
+> - No `repo` field on a submodule — it shares the parent module's repo
+> - No `port` or `stack` on a parent that has submodules
+> - Submodule names must be unique across the whole project — contracts live at
+>   `contracts/{submodule}/` and tasks.md uses `### {submodule}` headings directly
+
+**Removing a module or submodule:**
+- Check whether any `features/*/tasks.md` has a `### {name}` section (module name for
+  simple modules, submodule name for submodules).
+  If so, warn: "`{name}` has tasks in {feature(s)}. Removing it from config won't delete those tasks. Remove anyway? (yes/no)"
+- Otherwise confirm: "Remove `{name}` from the project? (yes/no)"
+- If removing the **last submodule** of a module, ask: "That's the last submodule of
+  `{module}`. Convert it back to a standalone module (needs a port and stack), or remove
+  the whole module?"
 
 **Updating a field:**
 - Show the current value, then ask for the new one:
   "`{module}.{field}` is currently `{old}`. What should it be?"
+- Submodule fields use the path `{module}.submodules[{sub}].{field}` — e.g.
+  "`webapps.submodules[admin].port` is currently `3001`. What should it be?"
+- Refuse to set `port` or `stack` on a parent with submodules, or `repo` on a
+  submodule — explain the rule instead.
 
 **Changing spec repo URL:**
 - "Current spec_repo is `{old}`. New URL?"
 
+**Editing project context (`CONTEXT.md`):**
+- Read `CONTEXT.md`. If missing, offer to create it with the template from `/forge-init`
+  Phase 6, asking the Phase 2 and Phase 4 questions to fill it.
+- Ask which section: "Which section? (What This Project Is / Business Goal / Actors /
+  Domain Glossary / Current State / Principles / Conventions / Out of Scope)"
+- Show the section's current content, then ask what to add, change, or remove.
+- Context edits go to `CONTEXT.md` only — never to CLAUDE.md or project.json.
+
 ## Step 4 — Preview & gate
 
 Show the before/after of exactly what will change:
@@ -69,19 +123,36 @@ 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."
+Adding a submodule:
+```
+Change preview:
+  modules[webapps].submodules  +  { name: reports, type: frontend,
+                                    stack: [React], port: 3003, path: apps/reports }
+```
+
+Converting a simple module to one with submodules, show the moved fields too:
+```
+Change preview:
+  modules[webapps].port   3000  →  (removed — moves to submodules)
+  modules[webapps].stack  [React]  →  (removed — moves to submodules)
+  modules[webapps].submodules  +  { name: admin, ... }
+```
+
+For CONTEXT.md edits, show the section before/after instead.
+
+> "Apply this change to `{file}`? 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}."
+Apply the change, preserving all other fields, sections, and formatting.
+Confirm: "Updated `{file}` — {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."
+If a module or submodule name changed, warn:
+> "Heads up: `{name}` is referenced by the module repo's `.forge/module.json`, by
+> `### {name}` headings in tasks.md, and by the `contracts/{name}/` folder. Update
+> those to match, or `/forge-implement` and `/forge-close` will break."
 
 ## Schema Reference
 
@@ -90,6 +161,7 @@ If a module name changed, warn:
   "project": "my-project",        // short slug, no spaces
   "version": "1.0",
   "modules": [
+    // Module WITHOUT submodules — port and stack on the module itself:
     {
       "name": "user-service",     // kebab-case, matches module.json in module repos
       "repo": "git@github.com:org/user-service.git",
@@ -97,6 +169,23 @@ If a module name changed, warn:
       "stack": ["Spring Boot 3", "Java 21"],
       "port": 8081,
       "description": ""           // optional, one sentence
+    },
+    // Module WITH submodules — NO port/stack/type on the parent;
+    // each submodule owns type, stack, port, path; NO repo on submodules:
+    {
+      "name": "webapps",
+      "repo": "git@github.com:org/webapps.git",
+      "description": "Web app mono-repo",
+      "submodules": [
+        {
+          "name": "admin",        // kebab-case, unique across the WHOLE project
+          "type": "frontend",     // backend | frontend | worker
+          "stack": ["React"],
+          "port": 3001,
+          "path": "apps/admin",   // relative path inside the parent repo
+          "description": ""       // optional, one sentence
+        }
+      ]
     }
   ],
   "spec_repo": "git@github.com:org/specs.git",
@@ -108,6 +197,10 @@ If a module name changed, warn:
 ## 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
+- `module.name` must be kebab-case and unique; submodule names must be unique across
+  the whole project (contracts and task headings use the submodule name directly)
+- `module.name` must match the `module` field in the module repo's `.forge/module.json`;
+  submodule names must match the `submodules[].name` entries there
+- A module has EITHER `port`+`stack` OR `submodules[]` — never both; submodules never
+  have a `repo` field
+- Never silently remove a module or submodule that has tasks referencing it — warn first

package/skills/forge-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "forge-init"
-description: "One-time initialization for a Forge spec repo. Walks through setup conversationally one question at a time, then writes .forge/project.json, CLAUDE.md, and directory scaffolding on confirmation."
+description: "One-time initialization for a Forge spec repo. Walks through setup conversationally one question at a time — project identity, project details, modules, principles — then writes .forge/project.json, CONTEXT.md, CLAUDE.md, and directory scaffolding on confirmation."
 argument-hint: "Optional: project name to skip the first prompt"
 compatibility: "Run once in a spec repo before any other forge skills. Safe to re-run — never overwrites existing files."
 when_to_use: >
@@ -40,7 +40,40 @@ _(Skip with 'none' if it's not set up yet — you can add it later with `/forge-
 
 ---
 
-## Phase 2 — Modules
+## Phase 2 — Project details
+
+These answers become `CONTEXT.md` — the project-wide domain context that
+`/forge-brainstorm` and `/forge-spec` read before planning, and that module repos
+see at `specs/CONTEXT.md` during implementation. Getting this right once saves
+re-explaining the project in every feature conversation.
+
+Start by offering the shortcut:
+> "If you have a project overview doc (README, pitch doc, Confluence page), paste it
+> and I'll extract these answers — otherwise I'll ask a few short questions."
+
+If a doc is pasted, extract what's covered and ask only about genuine gaps.
+Otherwise ask one question at a time:
+
+**Q1.** "Who uses this system? List the actors/roles and what each one does.
+_(e.g. 'customer — places orders; admin — manages the catalog; billing-worker — system actor')_"
+
+**Q2.** "What are the core domain concepts, in your team's own words?
+_(e.g. 'Order, Quote, Fulfillment — a Quote becomes an Order when accepted')_
+These become the domain glossary — the exact terms specs and contracts will use."
+
+**Q3.** "What's the business goal — what does success look like for this project?
+_(1–2 sentences, or 'skip')_"
+
+**Q4.** "What's the current state? Greenfield, or are there existing systems this
+replaces or integrates with?
+_(e.g. 'replacing a legacy PHP monolith; auth stays in Keycloak')_"
+
+Keep this phase capped at these four areas — deep per-feature questioning is
+`/forge-brainstorm`'s job, not init's.
+
+---
+
+## Phase 3 — Modules
 
 Collect modules one at a time. Each module is gathered field by field.
 
@@ -93,11 +126,11 @@ Then ask:
 > "Any more modules to add? (yes / no)"
 
 If yes, repeat from step 1 of this phase for the next module.
-If no, move to Phase 3.
+If no, move to Phase 4.
 
 ---
 
-## Phase 3 — Principles & conventions
+## Phase 4 — Principles & conventions
 
 Ask one at a time. "None" or "not yet" are valid answers — these sections can be filled
 in later with `/forge-config`.
@@ -116,7 +149,7 @@ Say 'none yet' to skip._"
 
 ---
 
-## Phase 4 — Preview & gate
+## Phase 5 — Preview & gate
 
 Show a full preview of what will be written:
 
@@ -128,13 +161,20 @@ Ready to initialize. Here's what I'll create:
   modules: {n} module(s): {comma-separated names}
   spec_repo: {url or "not set"}
 
-CLAUDE.md
+CONTEXT.md
   Description: {description}
-  Modules: {n} listed
+  Actors: {n} listed
+  Domain glossary: {n} terms
+  Business goal: {one line or "skipped"}
+  Current state: {one line}
   Principles: {list or "none yet"}
   Conventions: {list or "none yet"}
   Out of scope: {list or "none yet"}
 
+CLAUDE.md
+  Modules: {n} listed
+  Forge workflow + structure + pointer to CONTEXT.md
+
 features/CHANGELOG.md
 contracts/.gitkeep
 .gitignore  ← append Forge entries
@@ -146,7 +186,7 @@ Wait for confirmation. Do not write anything before the user says yes.
 
 ---
 
-## Phase 5 — Write files
+## Phase 6 — Write files
 
 Write `.forge/project.json`:
 
@@ -200,11 +240,55 @@ Module **with** submodules — no `port` on the module; each submodule owns its
 }
 ```
 
-Write `CLAUDE.md`:
+Write `CONTEXT.md` — the single source of truth for project-wide domain context.
+Fill every section from the Phase 1, 2, and 4 answers; write "None defined yet." only
+where the user explicitly skipped:
+```markdown
+# {project-name} — Project Context
+
+> Domain context for all planning and implementation. `/forge-brainstorm` and
+> `/forge-spec` read this before any feature work; module repos see it at
+> `specs/CONTEXT.md`. Keep it current via `/forge-config`.
+
+## What This Project Is
+{description — 2–4 sentences built from the user's answers, not just the one-liner}
+
+## Business Goal
+{goal — or "Not defined yet."}
+
+## Actors
+| Actor | Who they are | What they do in the system |
+|-------|--------------|----------------------------|
+| {role} | {description} | {responsibilities} |
+
+## Domain Glossary
+| Term | Meaning |
+|------|---------|
+| {term} | {definition in the team's own words} |
+
+## Current State
+{greenfield / existing systems, integrations, migration notes}
+
+## Principles
+{list each as a bullet — or "None defined yet."}
+
+## Conventions
+{list each as a bullet — or "None defined yet."}
+
+## Out of Scope / Forbidden
+{list each as a bullet — or "None defined yet."}
+```
+
+Write `CLAUDE.md` — operational only; domain context lives in `CONTEXT.md`, never
+duplicate it here:
 ```markdown
 # {project-name}
 
-{description}
+{description — the 1–2 sentence version}
+
+## Project Context
+Actors, domain glossary, principles, and conventions live in `CONTEXT.md`.
+Read it before any brainstorm, spec, or planning work.
 
 ## Modules
 | Name | Type | Stack | Port |
@@ -226,18 +310,10 @@ Indent the submodule name with `↳` and omit port/stack from the parent row.)_
 4. `/forge-contract`   — generate Specmatic OpenAPI contracts
 5. `/forge-close {slug} {module}` — mark a module's tasks done (after module repo ships)
 
-Utilities: `/forge-status` (feature dashboard) · `/forge-config` (edit modules/ports)
-
-## Principles
-{list each as a bullet — or "None defined yet."}
-
-## Conventions
-{list each as a bullet — or "None defined yet."}
-
-## Out of Scope / Forbidden
-{list each as a bullet — or "None defined yet."}
+Utilities: `/forge-status` (feature dashboard) · `/forge-config` (edit modules/ports/context)
 
 ## Structure
+- `CONTEXT.md`                    — project-wide domain context (actors, glossary, principles)
 - `features/{slug}/brainstorm.md` — approved brainstorm summary
 - `features/{slug}/spec.md`       — requirements, flows, API list
 - `features/{slug}/tasks.md`      — per-module task breakdown with checkboxes
@@ -271,7 +347,10 @@ Run `git status` and confirm:
 
 ## Rules
 - One question per message — never ask multiple questions at once
-- Never write files before the user says yes in Phase 4
+- Never write files before the user says yes in Phase 5
+- Each fact lives in exactly one file: domain context in `CONTEXT.md`, machine config
+  in `.forge/project.json`, workflow instructions in `CLAUDE.md` — never duplicate
+  content across them
 - Never overwrite existing files
 - All written files must be complete — no unfilled placeholders
 - **Extract, don't re-ask**: if the user's answer contains information for upcoming fields

package/skills/forge-spec/SKILL.md

@@ -44,9 +44,10 @@ Before asking anything, research silently:
    - How Non-Functional requirements are typically written
    - Any related feature whose requirements this feature extends or depends on
 
-2. **CLAUDE.md** — note project principles and conventions.
+2. **CONTEXT.md** — note the actors, domain glossary, principles, and conventions.
    Any principle that implies a requirement for this feature?
    (e.g. "API contract before implementation" → this feature needs a contract requirement)
+   Use glossary terms verbatim in requirements — never invent synonyms for existing domain terms.
 
 3. **Brainstorm open items** — extract from the brainstorm summary:
    - Any item listed under **Open Questions** that wasn't resolved
@@ -58,7 +59,7 @@ Report findings:
 > "Before drafting, here's what I found:
 > - Related features: {list or 'none'}
 > - Unresolved from brainstorm: {open questions / assumptions — or 'none, all clear'}
-> - CLAUDE.md principles that apply: {list or 'none'}
+> - CONTEXT.md principles that apply: {list or 'none'}
 > - Naming convention: {e.g. 'REQ-N restarts per feature'}"
 
 ---