@khanhspring/forge-module 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhspring/forge-module",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Forge module repo skills for Claude Code — implement, contract-test, done, and more",
   "type": "module",
   "bin": {

package/skills/forge-contract-test/SKILL.md

@@ -15,11 +15,15 @@ disable-model-invocation: true
 Run or analyze Specmatic contract tests for this module.
 
 ## Pre-check
-- Read `.forge/module.json` for `contract_glob` and `test_base_url`.
+- Read `.forge/module.json`.
   If missing, say "Run forge-init to set up this module repo first."
+- Determine scope:
+  - Has no `submodules` key → single module; use top-level `contract_glob` and `test_base_url`.
+  - Has `submodules[]` → module with submodules; show one command block per submodule.
 
-## If $ARGUMENTS is empty — Output the test command
+## If $ARGUMENTS is empty — Output the test command(s)
 
+**Single-module repo:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Contract Tests: {module}
@@ -36,6 +40,24 @@ Contracts under test:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+**Module with submodules (one block per submodule):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Contract Tests: {submodule.name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Make sure {submodule.name} is running at {submodule.test_base_url}, then run:
+
+  specmatic test \
+    --contract "{submodule.contract_glob}" \
+    --testBaseURL {submodule.test_base_url}
+
+Contracts under test:
+{list files matching submodule.contract_glob}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+_(Repeat for each entry in `submodules[]`.)_
+
 ## If $ARGUMENTS contains test output — Analyze failures
 
 For each failure, provide:

package/skills/forge-done/SKILL.md

@@ -31,7 +31,10 @@ is handled separately by `/forge-close` in the spec repo.
 ## Step 1 — Read task list (read-only from submodule)
 
 Read `{spec_submodule_path}/features/{slug}/tasks.md`.
-Find the `### {module}` section. Extract all tasks with their checkbox state.
+
+- If `module.json` has no `submodules` key: find the `### {module}` section.
+- If `module.json` has `submodules[]`: find the `### {submodule.name}` section for each entry;
+  show them grouped by submodule name in Step 2.
 
 If `tasks.md` is missing:
 > "No tasks file found at `specs/features/{slug}/tasks.md`.
@@ -65,6 +68,7 @@ Wait for confirmation before continuing.
 
 ## Step 3 — Generate commit message
 
+**Module with no submodules:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Commit message
@@ -73,15 +77,33 @@ feat({module}): implement {feature-slug}
 
 - TASK-1: {title}
 - TASK-2: {title}
-- TASK-3: {title}
 
 Spec:     specs/features/{slug}/spec.md
-Tasks:    specs/features/{slug}/tasks.md
 Contract: specs/contracts/{module}/{slug}.yaml
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Then remind:
 > "Once committed and pushed, go to the spec repo and run:
-> `/forge-close {slug} {module}`
-> to mark your tasks as done and check if the feature is fully complete."
+> `/forge-close {slug} {module}`"
+
+**Module with submodules (tasks grouped by submodule):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Commit message
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+feat(webapps): implement {feature-slug}
+
+[admin]
+- TASK-3: {title}
+[portal]
+- TASK-4: {title}
+
+Spec: specs/features/{slug}/spec.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then remind — one `/forge-close` per submodule, using the **submodule name directly**
+(no parent prefix — same command you'd use if it were a standalone module):
+> "/forge-close {slug} admin
+> /forge-close {slug} portal"

package/skills/forge-implement/SKILL.md

@@ -25,10 +25,15 @@ presented the Implementation Plan and the user has explicitly confirmed it.
 ## Pre-check
 
 - Read `.forge/module.json` — if missing, say "Run `/forge-init` to set up this module repo first."
-- Get `module`, `spec_submodule_path`, `test_base_url`, `contract_glob` from module.json.
+- Get `spec_submodule_path` from module.json.
+- **Determine working scope:**
+  - `module.json` has no `submodules` → scope = the module itself; use top-level `test_base_url` and `contract_glob`.
+  - `module.json` has `submodules[]` → ask "Which submodule are you implementing? ({list submodule names})"
+    then use that submodule's `path`, `test_base_url`, and `contract_glob`.
 - Feature slug from $ARGUMENTS.
-  - If empty, scan `{spec_submodule_path}/features/*/tasks.md` for `### {module}` sections,
-    list features with pending tasks, ask which to implement.
+  - If empty, scan `{spec_submodule_path}/features/*/tasks.md` for `### {scope-name}` headings
+    (module name for simple modules, submodule name for submodules), list features with pending
+    tasks, ask which to implement.
 - Check `git submodule status` — if specs/ is out of date, say:
   > "Your specs submodule may be out of date. Run `git submodule update --remote specs` first, or continue with the current version?"
 
@@ -42,25 +47,29 @@ Load the feature documents silently:
 
 If `tasks.md` is missing → stop: "No tasks found. Run `/forge-tasks {slug}` in the spec repo first."
 
-**Determine which contract(s) apply to this module:**
-- Look for an own-module contract: `{spec_submodule_path}/contracts/{module}/{slug}.yaml`.
-- **If it exists** → this module *provides* the API. Use it as the source of truth for the
-  endpoints you implement.
-- **If it does NOT exist** (typical for frontend/consumer modules) → scan
+**Determine which contract(s) apply to this scope:**
+- The contract path is always `{spec_submodule_path}/contracts/{scope-name}/{slug}.yaml` where
+  `{scope-name}` is the module name (for simple modules) or the submodule name (for submodules).
+  Submodules use their own name — no parent prefix — so the path is identical to a standalone module.
+- **If the contract exists** → this scope *provides* the API. Use it as the source of truth.
+- **If it does NOT exist** (typical for frontend/consumer scopes) → scan
   `{spec_submodule_path}/contracts/*/{slug}.yaml` for sibling contracts. These are the APIs
-  this module *consumes*. Report:
-  > "No contract for `{module}` — this module consumes APIs from: {list backend modules}.
+  this scope *consumes*. Report:
+  > "No contract for `{scope-name}` — consuming APIs from: {list providers}.
   > I'll use their contracts as the integration source of truth."
 - If no contract exists anywhere for this feature → note it and continue with spec + tasks only.
 
 Then research the existing codebase — do this before asking any questions:
 
-1. **Read `CLAUDE.md`** — note architectural principles, conventions, and forbidden patterns.
-2. **Find similar existing endpoints** — look for controllers/routes with similar patterns to what the contract defines. Note how they're structured.
-3. **Find existing service/repository patterns** — how are services and data access layers organized in this codebase?
-4. **Find existing test patterns** — how are unit and integration tests structured? What test utilities exist?
-5. **Find existing error handling** — how does this service return errors? Does it match the `ApiError` schema (`shared/api-error.yaml`) in the contract — `code`, `message`, `traceId`, `details[]`?
-6. **Find existing auth/middleware** — how is authentication enforced on existing endpoints?
+1. **Read `{spec_submodule_path}/CONTEXT.md`** (if present) — project-wide domain context:
+   actors, domain glossary, principles, and forbidden patterns. Use glossary terms verbatim
+   when naming things — never invent synonyms for existing domain terms.
+2. **Read `CLAUDE.md`** — this repo's architectural principles, conventions, and forbidden patterns.
+3. **Find similar existing endpoints** — look for controllers/routes with similar patterns to what the contract defines. Note how they're structured.
+4. **Find existing service/repository patterns** — how are services and data access layers organized in this codebase?
+5. **Find existing test patterns** — how are unit and integration tests structured? What test utilities exist?
+6. **Find existing error handling** — how does this service return errors? Does it match the `ApiError` schema (`shared/api-error.yaml`) in the contract — `code`, `message`, `traceId`, `details[]`?
+7. **Find existing auth/middleware** — how is authentication enforced on existing endpoints?
 
 Report findings before asking questions:
 
@@ -178,7 +187,7 @@ Wait for the answer before continuing.
 - When **consuming** an API (frontend/client): send requests and parse responses exactly as the
   consumed contract defines — treat its shapes as fixed, code defensively against its error responses
 - If the contract looks wrong: "This looks like a contract issue — raise a PR in the spec repo"
-- Only implement tasks under `### {module}` in tasks.md — flag any cross-module work
+- Only implement tasks under `### {scope-name}` in tasks.md (module name or submodule name) — flag any cross-scope work
 - Follow existing codebase patterns found in Step 1 — consistency over personal preference
 - No code before the user confirms the plan in Step 4
 

package/skills/forge-init/SKILL.md

@@ -19,9 +19,9 @@ disable-model-invocation: false
 
 # Forge Init — Module Repo
 
-Initialize this repo as a Forge module repo (one module — backend or frontend).
-Research what's already in the codebase first, then ask one question at a time —
-pre-filling anything already detectable. Write all files in one go after confirmation.
+Initialize this repo as a Forge module repo. It may contain one module (a dedicated service or
+app) or multiple modules sharing the same repo to reduce overhead (a monorepo). Either way,
+research first, then ask one question at a time before writing anything.
 
 ## Pre-check
 If `.forge/module.json` already exists → say "Module repo already initialized." and stop.
@@ -34,9 +34,13 @@ Before asking anything, silently scan the repo and note:
 
 1. **Stack detection** — does `pom.xml`, `build.gradle`, `package.json`, `go.mod`, `requirements.txt`, or similar exist? What versions are declared?
 2. **Port detection** — is a port configured in `application.yml`, `application.properties`, `.env`, `.env.example`, or `docker-compose.yml`?
-3. **Submodule** — does `specs/` already exist as a directory or submodule?
+3. **Specs submodule** — does `specs/` already exist as a directory or submodule?
 4. **CI** — does `.github/workflows/` already exist? Any contract test workflow present?
 5. **Existing CLAUDE.md** — already has project context written?
+6. **Monorepo signals** — does `nx.json`, `turbo.json`, `lerna.json`, `pnpm-workspace.yaml`, or
+   a `workspaces` key in `package.json` exist? Is there an `apps/` or `packages/` directory with
+   multiple sub-directories each containing their own `package.json`, `pom.xml`, etc.?
+   If yes, list the detected sub-apps (directory names).
 
 Report findings before asking anything:
 
@@ -45,9 +49,38 @@ Report findings before asking anything:
 > - Port: {detected port — or 'not found in config'}
 > - specs/ submodule: {exists / not present}
 > - GitHub Actions: {exists / not present}
+> {if monorepo signals}: - Looks like a monorepo — detected sub-apps: {list of dir names}
 >
 > I'll use these as defaults — just confirm or correct as we go."
 
+**If monorepo/multi-module signals were found**, ask immediately after the report:
+> "This looks like a module with submodules ({names}).
+> Should I configure them as submodules so each gets its own tasks and contracts? (yes / no)"
+
+If yes → collect submodule details in Step 2-B before the main questions.
+If no → proceed as a single module.
+
+---
+
+## Step 2-B — Submodule collection (only when confirmed)
+
+Submodules share the parent module's repo — they are not separate repos.
+Collect them one at a time. Pre-fill from what was detected and ask the user to confirm or correct:
+
+- "Submodule name? _(Must match a `name` under this module's `submodules` in the spec repo's `project.json`; default: `{detected-dir-name}`)_"
+- "Type? (backend / frontend / worker)"
+- "Stack? (detected: {stack-if-found} — or enter manually)"
+- "Port? _(each submodule has its own port — detected: {port-if-found})_"
+- "Path within this repo? (default: `{detected-path}`)"
+
+Confirm: "`{sub}` — {type} — {stack} — :{port} — {path}. Another submodule? (yes / no)"
+
+**Rules enforced here:**
+- Submodules have no `repo` field — they are in the same repo as the parent module
+- Port is collected per submodule; the parent module has no `port`
+
+After collecting all submodules, continue to Step 2 (Q4 port will be skipped automatically).
+
 ---
 
 ## Step 2 — Questions (one at a time)
@@ -56,7 +89,7 @@ Ask one question per message. Wait for the answer before asking the next.
 Where research already gives a confident answer, present it as a default to confirm
 rather than asking from scratch.
 
-**Q1 — Module name**
+**Q1 — Module name** _(skip if Step 2-B was run)_
 > "What's the module name for this repo?
 > _(Must exactly match a `name` entry in the spec repo's `.forge/project.json`)_"
 
@@ -75,7 +108,7 @@ If `specs/` already exists:
 If not:
 > "What's the spec repo URL? (it will be added as a git submodule at `specs/`)"
 
-**Q4 — Port**
+**Q4 — Port** _(skip entirely if Step 2-B was run — port belongs to each submodule, not the module)_
 
 If port was detected in Step 1:
 > "I found port `{port}` in your config — is that the right local dev port? (yes / enter different port)"
@@ -129,9 +162,14 @@ Ready to initialize. Here's what I'll do:
   git submodule update --init --recursive
 
 .forge/module.json
-  module:         {module-name}
-  test_base_url:  http://localhost:{port}
-  contract_glob:  specs/contracts/{module-name}/*.yaml
+  {if single app}
+  module:        {module-name}
+  test_base_url: http://localhost:{port}
+  contract_glob: specs/contracts/{module-name}/*.yaml
+  {if submodules}
+  submodules:
+    {sub-name}  path:{path}  :{port}  contract: specs/contracts/{sub-name}/*.yaml
+    ...
 
 CLAUDE.md
   Module:       {module-name}
@@ -161,6 +199,8 @@ git submodule update --init --recursive
 ```
 
 Write `.forge/module.json`:
+
+**For a single-app module** (no sub-apps):
 ```json
 {
   "module": "{module-name}",
@@ -171,17 +211,42 @@ Write `.forge/module.json`:
 }
 ```
 
+**Module with submodules** — no top-level `port` or `test_base_url`; each submodule owns those.
+Submodules have no `repo` field — they are in the same repo as the parent module:
+```json
+{
+  "module": "{module-name}",
+  "spec_submodule_path": "specs",
+  "specmatic_version": "2.x",
+  "submodules": [
+    {
+      "name": "{sub-name}",
+      "path": "{relative-path}",
+      "test_base_url": "http://localhost:{port}",
+      "contract_glob": "specs/contracts/{sub-name}/*.yaml"
+    }
+  ]
+}
+```
+
 Write `CLAUDE.md`:
 ```markdown
 # {module-name}
 
 {description}
 
-**Stack:** {stack}
-**Port:** {port}
+_(Single app: show Stack + Port inline. Monorepo: replace with a table.)_
+
+**Stack:** {stack}  **Port:** {port}
+
+— or for a monorepo —
+
+| Module | Stack | Port | Path |
+|--------|-------|------|------|
+| {name} | {stack} | {port} | {path} |
 
 ## Forge Workflow
-1. `/forge-tasks`         — see all pending tasks for this module
+1. `/forge-tasks`         — see all pending tasks for this repo's module(s)
 2. `/forge-implement`     — implement a feature task by task
 3. `/forge-contract-test` — run Specmatic contract tests
 4. `/forge-done`          — confirm tasks done + generate commit message
@@ -191,6 +256,8 @@ Write `CLAUDE.md`:
 Linked via git submodule at `specs/`.
 Run `git submodule update --remote specs` before starting a new feature,
 and again after `/forge-close` is run in the spec repo to sync task status.
+Project-wide domain context (actors, glossary, principles) lives at `specs/CONTEXT.md`
+— read it before implementing.
 
 ## Principles
 {list each as a bullet — or "None defined yet."}
@@ -237,4 +304,8 @@ Run `git status` and confirm:
 - Never overwrite existing files
 - All written files must be complete — no unfilled placeholders
 - `module` in module.json must exactly match the name in the spec repo's project.json
+- **Extract, don't re-ask**: if the user's answer contains information for upcoming fields
+  (e.g. "it's a NestJS app on port 3000 at apps/auth-ui"), extract and fill those fields
+  silently — only ask about what is genuinely missing. Never ask a question the user has
+  already answered, even indirectly.
 - If the user provides multiple answers in one message, accept them gracefully and move forward

package/skills/forge-tasks/SKILL.md

@@ -22,7 +22,13 @@ Show all tasks assigned to this module across all features.
 
 ## Steps
 
-Scan `{spec_submodule_path}/features/*/tasks.md` → find `### {module}` sections → extract tasks
+Determine the set of task headings to look for:
+- `module.json` has no `submodules` → look for `### {module}` (one heading).
+- `module.json` has `submodules[]` → look for `### {submodule.name}` for each entry.
+  Submodule task headings use the submodule's own name — no parent prefix — so they are
+  identical to standalone module headings and can be promoted without touching tasks.md.
+
+Scan `{spec_submodule_path}/features/*/tasks.md` → find all matching headings → extract tasks
 with their checkbox state and the parent feature's `Status`.
 
 ```
@@ -42,6 +48,22 @@ Feature: user-profile  [Open]
 2 features  ·  4 remaining  ·  1 done
 ```
 
+For a module with submodules, group tasks by submodule under each feature:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tasks for: webapps  (submodules: admin · landing · portal)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Feature: user-registration  [Open]
+  [admin]
+  - [ ] TASK-3 [ui] Registration form
+  [portal]
+  - [ ] TASK-4 [ui] Registration confirmation page
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1 feature  ·  2 remaining  ·  0 done
+```
+
 If no tasks reference this module across any feature:
 > "No tasks found for `{module}`. Either no feature targets this module yet, or the specs
 > submodule is out of date — try `git submodule update --remote specs`."