thachvd-kit 1.0.28 → 1.0.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/.agent/docs/getting-started.md +28 -25
  2. package/.agent/docs/workflow.md +10 -9
  3. package/.agent/rules/GEMINI.md +10 -9
  4. package/.agent/workflows/forge-debug.md +12 -0
  5. package/.agent/workflows/forge-fast.md +22 -0
  6. package/.agent/workflows/forge-release.md +12 -0
  7. package/.agent/workflows/forge-research.md +24 -0
  8. package/.agent/workflows/forge-review.md +12 -0
  9. package/.agent/workflows/forge-task.md +37 -0
  10. package/README.md +18 -17
  11. package/bin/cli.js +139 -65
  12. package/commands/forge-debug.md +12 -0
  13. package/commands/forge-fast.md +22 -0
  14. package/commands/forge-release.md +12 -0
  15. package/commands/forge-research.md +24 -0
  16. package/commands/forge-review.md +12 -0
  17. package/commands/forge-task.md +37 -0
  18. package/package.json +2 -1
package/.agent/docs/getting-started.md CHANGED
@@ -2,28 +2,30 @@
2
2
 
3
3
  Read this after `thachvd-kit init`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
4
4
 
5
- ## Client Command Map
5
+ ## Forge Command Map
6
6
 
7
- | Client | Task router | Simple fix | Bug fix | Feature spec | Release |
8
- |---|---|---|---|---|---|
9
- | Codex | `/prompts:task` | `/prompts:simple` | `/prompts:debug` | `/prompts:spec` | `/prompts:release` |
10
- | Antigravity | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
11
- | Claude Code | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
12
- | Cursor | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
7
+ | Client | Task | Fast | Debug | Research | Review | Release |
8
+ |---|---|---|---|---|---|---|
9
+ | Codex | `$forge-task` | `$forge-fast` | `$forge-debug` | `$forge-research` | `$forge-review` | `$forge-release` |
10
+ | Antigravity | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
11
+ | Claude Code | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
12
+ | Cursor | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
13
13
 
14
- Codex reads custom prompts from `~/.codex/prompts`. Antigravity reads workspace workflows from `.agent/workflows`. Claude Code reads project skills from `.claude/skills/<name>/SKILL.md`. Cursor reads commands from `.cursor/commands`.
14
+ Forge commands accept free-form text after the command and continue the selected workflow in the same turn. Plain questions remain normal chat; edit requests without a command are implicitly routed as `forge-task`.
15
15
 
16
- ## Start Every Task With The Router
16
+ Codex Forge skills live in `~/.codex/skills/forge-*/SKILL.md`. Antigravity Forge workflows live in `.agent/workflows/forge-*.md`. Claude Code Forge commands live in `.claude/commands/forge-*.md`. Cursor Forge commands live in `.cursor/commands/forge-*.md`.
17
17
 
18
- In Codex, use `/prompts:task <request>` before editing whenever the route is not already obvious. Other clients can read `.agent/workflows/task.md` directly. It must produce:
18
+ ## Start Every Task With Forge
19
+
20
+ Use the matching Forge command before editing whenever the request is not a simple question. `forge-task` must route internally and continue; it must not stop by asking the member to type a second command.
19
21
 
20
22
  ```text
21
- ROUTE: question | simple | feature | bug | review | release | multi-domain
23
+ ROUTE: question | fast | feature | bug | research | review | release | multi-domain
22
24
  WORKFLOW: [exact .agent/workflows/<name>.md file]
23
25
  SKILLS: [matching skills, or none]
24
26
  AGENTS: [matching specialist agents, or none]
25
- GATE: fast-path | standard
26
- NEXT: [the next command or action]
27
+ GATE: fast-path | standard | human-approval
28
+ ACTION: [what the agent is doing next in this turn]
27
29
  ```
28
30
 
29
31
  A workflow is the process and its gates. A skill is the method or checklist. An agent is the specialist role. Chat alone is not a route: the member must select the route and invoke the matching workflow or explicitly choose the question path.
@@ -33,22 +35,23 @@ A workflow is the process and its gates. A skill is the method or checklist. An
33
35
  | Situation | Command | Gate | Required next step |
34
36
  |---|---|---|---|
35
37
  | Explain, inspect, or brainstorm only | direct answer or `/brainstorm` | none | no code until the request becomes actionable |
36
- | One obvious local fix | `/prompts:simple <request>` in Codex | fast-path | inspect -> edit -> focused verify |
37
- | New behavior, multi-file change, unclear scope, or >~30 min | `/prompts:task` -> `/brainstorm` -> `/prompts:spec` when needed -> `/plan` | standard | wait for approval before implementation |
38
- | Bug, regression, failing test, or unknown error | `/prompts:debug <symptom>` in Codex | bug | reproduce -> isolate -> regression test -> fix -> verify |
39
- | Pre-merge or independent review | `/review` | review | five-axis review; resolve blocking findings |
40
- | Version, tag, npm publish, or deployment | `/prompts:release` in Codex | release | release checklist; never fast-path |
38
+ | One obvious local fix | `/forge-fast <request>` | fast-path | inspect -> edit -> focused verify |
39
+ | New behavior, multi-file change, unclear scope, or >~30 min | `/forge-task <request>` | standard | route -> research/spec/plan -> approval when required -> continue |
40
+ | Bug, regression, failing test, or unknown error | `/forge-debug <symptom>` | bug | reproduce -> isolate -> regression test -> fix -> verify |
41
+ | Research request | `/forge-research <question>` | research | evidence report, no edits |
42
+ | Pre-merge or independent review | `/forge-review` | review | five-axis review; resolve blocking findings |
43
+ | Version, tag, npm publish, or deployment | `/forge-release` | release | release checklist; never fast-path |
41
44
  | Frontend + backend + data/security together | `/orchestrate` | standard | plan -> approval -> specialist work -> integration verify |
42
45
 
43
46
  ## Standard Feature Flow
44
47
 
45
- The gated sequence is Spec -> Plan -> Implement -> Review: `/prompts:task` -> `/brainstorm` -> `/prompts:spec` when scope is ambiguous or multi-file -> `/plan` -> user approves the plan -> implementation -> `/test` -> `/review` -> final verification -> commit/push.
48
+ The gated sequence is Spec -> Plan -> Implement -> Review. `/forge-task` manages this sequence internally and pauses only at the explicit user approval gate before implementation.
46
49
 
47
50
  The plan is a gate, not a suggestion. Do not start product-code implementation before explicit approval. Load only the relevant specialist agent and skills, such as `$frontend-design`, `$api-design`, or `$webapp-testing`.
48
51
 
49
52
  ## Bug Fix Flow
50
53
 
51
- Use Codex `/prompts:debug <symptom>`, not the feature flow, when something is failing or the root cause is unknown:
54
+ Use `/forge-debug <symptom>`, not the feature flow, when something is failing or the root cause is unknown:
52
55
 
53
56
  1. Capture the exact symptom, environment, reproduction, and expected result.
54
57
  2. Inspect the relevant code path with MCP/codegraph when available.
@@ -62,7 +65,7 @@ Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns` for t
62
65
 
63
66
  ## Simple Fast Path
64
67
 
65
- Use Codex `/prompts:simple <request>` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
68
+ Use `/forge-fast <request>` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
66
69
 
67
70
  ```text
68
71
  FAST_PATH: simple-fix
@@ -70,18 +73,18 @@ REASON: [why Spec/Plan/Review are not needed]
70
73
  SCOPE: [file or narrow area]
71
74
  ```
72
75
 
73
- This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route with Codex `/prompts:task`.
76
+ This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route internally through `forge-task`.
74
77
 
75
78
  ## Command And Skill Map
76
79
 
77
80
  - `/brainstorm`: clarify intent and tradeoffs; no code.
78
- - Codex `/prompts:spec`: define requirements and acceptance criteria; no code.
81
+ - `forge-research`: evidence-based codebase/technical/domain research; no product-code edits.
79
82
  - `/plan`: create an approved implementation plan; no code before approval.
80
83
  - `/enhance` or `/create`: implement an approved feature with the relevant specialist agent.
81
- - Codex `/prompts:debug`: systematic root-cause investigation and regression protection.
84
+ - `forge-debug`: systematic root-cause investigation and regression protection.
82
85
  - `/test`: add or run tests and assess coverage.
83
86
  - `/review`: five-axis review before completion or merge.
84
- - Codex `/prompts:release`: verify, version, tag, publish, and verify npm output.
87
+ - `forge-release`: verify, version, tag, publish, and verify npm output.
85
88
  - `$clean-code` and `$verification-before-completion`: default implementation hygiene.
86
89
  - `$webapp-testing`: browser/UI verification; use Playwright when available.
87
90
 
package/.agent/docs/workflow.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  1. Read AGENTS.md.
6
6
  2. Read .agent/docs/project.md.
7
- 3. Route the request with Codex `/prompts:task <request>` when the path is not obvious; otherwise read `.agent/workflows/task.md` directly.
7
+ 3. Use `/forge-task <request>` (or `$forge-task <request>` in Codex) when the request changes code and the path is not obvious.
8
8
  4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
9
9
  5. Check if MCP servers (like `codegraph`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
10
10
 
@@ -13,11 +13,12 @@
13
13
  | Situation | Command | Workflow / gate |
14
14
  |---|---|---|
15
15
  | Question or analysis only | direct answer | no edits |
16
- | One obvious local fix | Codex `/prompts:simple` | `.agent/workflows/simple.md`, fast-path |
17
- | Bug, regression, failing test, or unknown error | Codex `/prompts:debug` | `.agent/workflows/debug.md`, evidence-first |
18
- | New behavior, multi-file change, or unclear scope | `/brainstorm` -> Codex `/prompts:spec` when needed -> `/plan` | spec/plan approval -> implement -> review |
19
- | Pre-merge review | `/review` | `.agent/workflows/review.md`, five-axis |
20
- | npm version, tag, publish, or deployment | Codex `/prompts:release` | `.agent/workflows/release.md`, release gate |
16
+ | One obvious local fix | `/forge-fast` | `.agent/workflows/simple.md`, fast-path |
17
+ | Bug, regression, failing test, or unknown error | `/forge-debug` | `.agent/workflows/debug.md`, evidence-first |
18
+ | Research request | `/forge-research` | evidence report, no edits |
19
+ | New behavior, multi-file change, or unclear scope | `/forge-task` | research/spec/plan approval -> implement -> review |
20
+ | Pre-merge review | `/forge-review` | `.agent/workflows/review.md`, five-axis |
21
+ | npm version, tag, publish, or deployment | `/forge-release` | `.agent/workflows/release.md`, release gate |
21
22
  | Several specialist domains | `/orchestrate` | plan -> approval -> parallel work -> integration verify |
22
23
 
23
24
  If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
@@ -35,7 +36,7 @@ If a task is not clearly simple, use the standard flow. Never use the fast path
35
36
 
36
37
  ## Implementation Flow
37
38
 
38
- For Codex `/prompts:simple` fixes, state the fast-path decision before editing:
39
+ For `/forge-fast` fixes, state the fast-path decision before editing:
39
40
 
40
41
  ```text
41
42
  FAST_PATH: simple-fix
@@ -52,7 +53,7 @@ Then:
52
53
  5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
53
54
  6. Summarize changed files and verification evidence.
54
55
 
55
- For bugs, use Codex `/prompts:debug` with `$systematic-debugging`, the `debugger` agent, and `testing-patterns`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
56
+ For bugs, use `/forge-debug` with `$systematic-debugging`, the `debugger` agent, and `testing-patterns`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
56
57
 
57
58
  For features or refactors, this flow runs *inside* the gated flow defined in AGENTS.md (spec -> plan -> implement -> review) — steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory `.agent/workflows/review.md` gate.
58
59
 
@@ -60,7 +61,7 @@ For features or refactors, this flow runs *inside* the gated flow defined in AGE
60
61
 
61
62
  A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
62
63
 
63
- The Spec checkbox may be skipped only when the documented Codex `/prompts:simple` fast-path protocol is stated and its criteria are met.
64
+ The Spec checkbox may be skipped only when the documented `/forge-fast` protocol is stated and its criteria are met.
64
65
 
65
66
  - [ ] `.agent/workflows/spec.md` exit criteria met (or explicitly skipped as a trivial/self-contained change)
66
67
  - [ ] `.agent/workflows/plan.md` produced a plan file, approved by the user
package/.agent/rules/GEMINI.md CHANGED
@@ -29,20 +29,21 @@ Load only the agent, skill, or workflow files relevant to the current task.
29
29
 
30
30
  ## Execution
31
31
 
32
- - Route every task before editing. Use `/task <request>` when the correct path is not obvious.
33
- - Workspace workflows are available as `/task`, `/simple`, `/debug`, `/spec`, and `/release` from `.agent/workflows/`.
32
+ - Route every task before editing. Use `/forge-task <request>` when the correct path is not obvious.
33
+ - Forge workflows are available as `/forge-task`, `/forge-fast`, `/forge-debug`, `/forge-research`, `/forge-review`, and `/forge-release`.
34
34
  - Questions and analysis: answer directly; do not edit code.
35
- - Simple fix: use `/simple <request>` only for one-file, unambiguous changes with no behavior or contract change.
36
- - Bug or failing behavior: use `/debug <symptom>` and follow the evidence-first root-cause flow.
37
- - Feature or refactor: use `/brainstorm` for discovery, `/spec` for ambiguous or multi-file scope, then `/plan`, wait for approval, implement, test, and `/review`.
38
- - Pre-merge review: use `/review`.
39
- - Release or npm publish: use `/release`; never use the simple fast path.
35
+ - Simple fix: use `/forge-fast <request>` only for one-file, unambiguous changes with no behavior or contract change.
36
+ - Bug or failing behavior: use `/forge-debug <symptom>` and follow the evidence-first root-cause flow.
37
+ - Research: use `/forge-research <question>` for evidence-based research without product-code edits.
38
+ - Feature or refactor: use `/forge-task <request>`; it handles research, spec, plan, approval, implementation, test, and review in sequence.
39
+ - Pre-merge review: use `/forge-review`.
40
+ - Release or npm publish: use `/forge-release`; never use the simple fast path.
40
41
  - UI work: use relevant frontend design skills before editing.
41
42
  - Security or deploy work: run the matching checklist before claiming done.
42
43
 
43
- ### Fast Path (`/simple`)
44
+ ### Fast Path (`/forge-fast`)
44
45
 
45
- The fast path bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection or verification. State `FAST_PATH: simple-fix`, the reason, and the narrow scope before editing. Re-route with `/task` if the scope expands.
46
+ The fast path bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection or verification. State `FAST_PATH: simple-fix`, the reason, and the narrow scope before editing. Re-route with `/forge-task` if the scope expands.
46
47
 
47
48
  ### Gated Flow (feature or refactor)
48
49
 
package/.agent/workflows/forge-debug.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Investigate and fix a bug with evidence-first root-cause analysis.
3
+ argument-hint: [SYMPTOM]
4
+ ---
5
+
6
+ # Forge Debug
7
+
8
+ Symptom:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/debug.md`, use `$systematic-debugging`, the `debugger` agent, and `testing-patterns` when available. Reproduce the symptom, inspect the relevant code path with codegraph/MCP, form and test hypotheses, identify the root cause, add regression protection when practical, make the smallest fix, and verify it. Do not patch by guesswork and do not stop by asking the member to invoke another command.
package/.agent/workflows/forge-fast.md ADDED
@@ -0,0 +1,22 @@
1
+ ---
2
+ description: Execute a trivial, unambiguous change with focused verification.
3
+ argument-hint: [REQUEST]
4
+ ---
5
+
6
+ # Forge Fast Path
7
+
8
+ Request:
9
+
10
+ $ARGUMENTS
11
+
12
+ Use this path only for one obvious file or tiny local change with no behavior, API, schema, security, CI, dependency, workflow, or release contract change.
13
+
14
+ Before editing, state exactly:
15
+
16
+ ```text
17
+ FAST_PATH: simple-fix
18
+ REASON: [why Spec, Plan, and feature Review are not needed]
19
+ SCOPE: [file or narrow area]
20
+ ```
21
+
22
+ Inspect the target, make the smallest change, run focused verification, and report evidence. If the scope expands, stop and internally re-route through the appropriate Forge workflow. Never skip inspection or verification.
package/.agent/workflows/forge-release.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Verify, version, publish, and verify the thachvd-kit npm release.
3
+ argument-hint: [RELEASE_REQUEST]
4
+ ---
5
+
6
+ # Forge Release
7
+
8
+ Release request:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/release.md` and run the release gate. Confirm the working tree, review status, version, npm authentication, verification output, and package contents before publishing. Never use the fast path. Do not run `npm publish` until the release gate is satisfied and the human has confirmed the final version and publish action. After publishing, verify the registry version and the installed package output.
package/.agent/workflows/forge-research.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ description: Research the codebase, technical topic, or domain without editing product code.
3
+ argument-hint: [QUESTION]
4
+ ---
5
+
6
+ # Forge Research
7
+
8
+ Research question:
9
+
10
+ $ARGUMENTS
11
+
12
+ Do not edit product code. First classify the research as codebase, external technical, or domain research. For codebase research, use codegraph/MCP first. For external research, use authoritative current sources only when needed and cite them. Return exactly:
13
+
14
+ ```text
15
+ RESEARCH_STATUS: complete | blocked
16
+ QUESTION: [what was investigated]
17
+ ASSUMPTIONS: [explicit assumptions]
18
+ FINDINGS: [evidence-based findings]
19
+ SOURCES: [file paths, symbols, MCP evidence, or URLs]
20
+ RISKS: [known risks and unknowns]
21
+ OPTIONS: [possible approaches and tradeoffs]
22
+ RECOMMENDATION: [recommended direction]
23
+ OPEN_QUESTIONS: [unresolved questions]
24
+ ```
package/.agent/workflows/forge-review.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Review a change across correctness, simplicity, architecture, security, and performance.
3
+ argument-hint: [SCOPE]
4
+ ---
5
+
6
+ # Forge Review
7
+
8
+ Review scope:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/review.md` and inspect the relevant diff, task, and verification evidence. Review all five axes. Report findings first, ordered by severity, using `BLOCKING`, `SUGGESTION`, `NIT`, or `QUESTION`. Do not edit code during review unless the member explicitly asks for fixes after the findings.
package/.agent/workflows/forge-task.md ADDED
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: Route a request and continue the selected Forge workflow in this turn.
3
+ argument-hint: [REQUEST]
4
+ ---
5
+
6
+ # Forge Task Orchestrator
7
+
8
+ The request supplied with this command is:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `AGENTS.md`, `.agent/docs/project.md`, and `.agent/docs/workflow.md` before editing.
13
+
14
+ Classify the request internally as `question`, `fast`, `feature`, `bug`, `research`, `review`, `release`, or `multi-domain`. Then continue the selected workflow in this same turn. Do not stop after printing a `NEXT` command and do not ask the member to invoke another Forge command for ordinary routing.
15
+
16
+ Use this compact status header when useful:
17
+
18
+ ```text
19
+ REQUEST: [original request]
20
+ ROUTE: [route]
21
+ WORKFLOW: [exact workflow file]
22
+ SKILLS: [matching skills]
23
+ AGENTS: [matching agents]
24
+ GATE: fast-path | standard | human-approval
25
+ ACTION: [what you are doing now]
26
+ ```
27
+
28
+ Rules:
29
+
30
+ - Questions and analysis: answer directly with no edits.
31
+ - Trivial one-file changes: apply the `forge-fast` protocol, including focused verification.
32
+ - Bugs or unknown failures: reproduce, isolate root cause, add regression protection, fix, and verify.
33
+ - Research: use codegraph/MCP first for repository questions, use authoritative external sources when needed, and do not edit code.
34
+ - Features and refactors: follow spec -> plan -> approval -> implement -> test -> review. Stop only at the documented human approval gate.
35
+ - Reviews: run the five-axis review and report findings first.
36
+ - Releases: follow `.agent/workflows/release.md`; never use the fast path.
37
+ - If the request is empty or unsafe to classify, ask one concise clarification question.
package/README.md CHANGED
@@ -60,48 +60,49 @@ Skills work best through progressive disclosure: the agent should first see skil
60
60
  - Keep `.agent/skills` as the complete shared source from the kit.
61
61
  - Let `thachvd-kit` copy selected skills to `~/.codex/skills/` for Codex and `.claude/skills` for Claude Code.
62
62
  - Make every `SKILL.md` frontmatter `description` specific: include when to use it, trigger phrases, and boundaries.
63
- - Run `thachvd-kit --help` to see a compact workflow guide. In Codex, custom prompts appear as `/prompts:task`, `/prompts:simple`, `/prompts:debug`, `/prompts:spec`, and `/prompts:release` after `init` and a Codex restart. Built-in commands such as `/plan` and `/review` remain unchanged.
63
+ - Run `thachvd-kit --help` to see a compact workflow guide. Forge commands appear after `init` and a client restart.
64
64
  - Use explicit prompts when implicit matching misses, for example `Use $webapp-testing to verify this UI` or `Use $clean-code before refactoring`.
65
65
  - Restart Codex or Claude Code if a newly copied or edited skill does not appear.
66
66
 
67
67
  ## Development Workflow
68
68
 
69
- After install, every AI client starts at the task router when the route is not already obvious. In Codex, use `/prompts:task <request>`; other clients can read `.agent/workflows/task.md` directly. The router selects the smallest safe workflow and relevant skills/agents; it does not force the full feature gate onto every request.
69
+ After install, Forge is the member-facing command suite. It accepts free-form text after the command, routes the request, and continues the selected workflow in the same turn. Questions remain normal chat; edit requests without a command are implicitly routed as `forge-task`.
70
70
 
71
71
  ### Client Commands
72
72
 
73
- | Client | Router | Fast path | Bug flow | Feature spec | Release |
73
+ | Client | Task | Fast path | Bug flow | Research | Review | Release |
74
74
  |---|---|---|---|---|---|
75
- | Codex | `/prompts:task` | `/prompts:simple` | `/prompts:debug` | `/prompts:spec` | `/prompts:release` |
76
- | Antigravity | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
77
- | Claude Code | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
78
- | Cursor | `/task` | `/simple` | `/debug` | `/spec` | `/release` |
75
+ | Codex | `$forge-task` | `$forge-fast` | `$forge-debug` | `$forge-research` | `$forge-review` | `$forge-release` |
76
+ | Antigravity | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
77
+ | Claude Code | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
78
+ | Cursor | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
79
79
 
80
- `init` installs these from the same source: Codex prompts in `~/.codex/prompts`, Antigravity workflows in `.agent/workflows`, Claude Code skills in `.claude/skills`, and Cursor commands in `.cursor/commands`. Restart or reload the client after the first installation if commands do not appear.
80
+ `init` installs these from `commands/`: Codex skills in `~/.codex/skills/forge-*`, Antigravity workflows in `.agent/workflows/forge-*`, Claude Code commands in `.claude/commands/forge-*`, and Cursor commands in `.cursor/commands/forge-*`. Restart or reload the client after installation.
81
81
 
82
82
  | Situation | Command | Required flow |
83
83
  |---|---|---|
84
84
  | Question or analysis | direct answer | no edits |
85
- | One obvious local fix | `/prompts:simple <request>` in Codex | inspect → edit → focused verify |
86
- | Bug or failing behavior | `/prompts:debug <symptom>` in Codex | reproduce → root cause → regression test → fix → verify |
87
- | New behavior or refactor | `/prompts:task` → `/brainstorm` → `/prompts:spec` when needed → `/plan` | approval → implement → test → `/review` |
88
- | Pre-merge review | `/review` | five-axis review; resolve blocking findings |
89
- | npm version/tag/publish | `/release` | release verification; never fast path |
85
+ | One obvious local fix | `/forge-fast <request>` | inspect → edit → focused verify |
86
+ | Bug or failing behavior | `/forge-debug <symptom>` | reproduce → root cause → regression test → fix → verify |
87
+ | Research request | `/forge-research <question>` | evidence report; no product-code edits |
88
+ | New behavior or refactor | `/forge-task <request>` | route → research/spec/plan → approval when required → implement → test → review |
89
+ | Pre-merge review | `/forge-review` | five-axis review; resolve blocking findings |
90
+ | npm version/tag/publish | `/forge-release` | release verification; never fast path |
90
91
  | Several specialist domains | `/orchestrate` | plan → approval → parallel work → integration verify |
91
92
 
92
93
  ### Standard Feature Flow
93
94
 
94
- `/prompts:task` → `/brainstorm` when needed → `/prompts:spec` for ambiguous or multi-file scope → `/plan` → explicit user approval → implementation → `/test` → `/review` → final verification → commit/push.
95
+ `/forge-task` manages Spec → Plan → Implement → Review internally and pauses only at the explicit user approval gate before implementation. It does not stop by printing a command for the member to run next.
95
96
 
96
97
  Workflow files define process and gates. Skills define methods/checklists. Agents provide specialist ownership. Members should invoke the command, not only describe the work in chat.
97
98
 
98
99
  ### Bug Fix Flow
99
100
 
100
- Use `/prompts:debug` in Codex for regressions, failing tests, exceptions, incorrect output, or any symptom with an unknown root cause. Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns`; reproduce the issue, inspect the code path, test hypotheses, add regression protection, make the smallest root-cause fix, and verify. Use `/review` when the change is cross-file or affects a shared contract.
101
+ Use `/forge-debug` for regressions, failing tests, exceptions, incorrect output, or any symptom with an unknown root cause. Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns`; reproduce the issue, inspect the code path, test hypotheses, add regression protection, make the smallest root-cause fix, and verify. Use `/forge-review` when the change is cross-file or affects a shared contract.
101
102
 
102
103
  ### Simple Fast Path
103
104
 
104
- Use `/prompts:simple` in Codex only for one obvious file, an unambiguous result, and no behavior, API, schema, security, CI, dependency, workflow, or release contract change. Before editing, state:
105
+ Use `/forge-fast` only for one obvious file, an unambiguous result, and no behavior, API, schema, security, CI, dependency, workflow, or release contract change. Before editing, state:
105
106
 
106
107
  ```text
107
108
  FAST_PATH: simple-fix
@@ -109,7 +110,7 @@ REASON: [why Spec/Plan/Review are not needed]
109
110
  SCOPE: [file or narrow area]
110
111
  ```
111
112
 
112
- This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection or verification. If the scope expands, stop and run `/prompts:task` again.
113
+ This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection or verification. If the scope expands, re-route internally through `forge-task`.
113
114
 
114
115
  Claude Code has a Stop hook that checks the standard feature/refactor gate. Codex, Antigravity, and Cursor use the same written routing rules through `AGENTS.md`, `.cursorrules`, and `.agent/rules/GEMINI.md`.
115
116
 
package/bin/cli.js CHANGED
@@ -7,8 +7,9 @@ const prompts = require('prompts');
7
7
  const pc = require('picocolors');
8
8
  const packageJson = require('../package.json');
9
9
 
10
- const sourceDir = path.resolve(__dirname, '..');
11
- const targetDir = process.cwd();
10
+ const sourceDir = path.resolve(__dirname, '..');
11
+ const targetDir = process.cwd();
12
+ const FORGE_COMMANDS = ['forge-task', 'forge-fast', 'forge-debug', 'forge-research', 'forge-review', 'forge-release'];
12
13
 
13
14
  // --- Skill Resolver ---
14
15
 
@@ -145,33 +146,34 @@ ${pc.bold('What gets generated:')}
145
146
  .claude/skills/ Selected Claude Code project skills copied from .agent/skills
146
147
 
147
148
  ${pc.bold('Workflow guide:')}
148
- Every task /prompts:task Classify request and select workflow, skill, and agent
149
- Small obvious fix /prompts:simple Fast path; skips spec/plan/review but still verifies
149
+ Every task /forge-task Route and continue the selected workflow in this turn
150
+ Small obvious fix /forge-fast Fast path; skips spec/plan/review but still verifies
150
151
  Idea is fuzzy /brainstorm Explore options, tradeoffs, and recommended direction
151
- Scope needs a contract /prompts:spec Define requirements and acceptance criteria; no code yet
152
+ Research first /forge-research Evidence-based research; no product-code edits
153
+ Scope needs a contract /forge-task Handles research, spec, plan approval, implementation, and review
152
154
  New app from scratch /create Turn an app idea into plan + implementation flow
153
155
  Feature is clear /plan Create docs/PLAN-*.md first, no code yet
154
156
  Existing app update /enhance Add or change a feature in an existing codebase
155
- Bug or failing behavior /prompts:debug Investigate symptoms, root cause, fix
157
+ Bug or failing behavior /forge-debug Investigate symptoms, root cause, fix
156
158
  UI / UX work ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
157
159
  Run or add tests /test Generate tests, run tests, check coverage
158
160
  Preview locally /preview Start, stop, restart, or health-check dev server
159
161
  Deploy / infra /deploy Release, hosting, Docker, cloud, environment setup
160
- Pre-merge review /review Run the five-axis review before calling work complete
161
- Npm package release /prompts:release Verify, version, tag, publish, and verify the package
162
+ Pre-merge review /forge-review Run the five-axis review before calling work complete
163
+ Npm package release /forge-release Verify, version, tag, publish, and verify the package
162
164
  Project state /status Summarize stack, progress, preview, pending work
163
165
  Multi-domain work /orchestrate Coordinate frontend, backend, data, security, QA
164
166
 
165
167
  ${pc.bold('Common explicit skill prompts:')}
166
- In Codex, use /prompts:task to route this request before editing.
167
- In Codex, use /prompts:simple for a one-file fix with no behavior or contract change.
168
+ Use /forge-task to route and continue a request in one turn.
169
+ Use /forge-fast for a one-file fix with no behavior or contract change.
168
170
  Use /brainstorm for this feature idea before planning.
169
- In Codex, use /prompts:spec when requirements or scope need an explicit contract.
171
+ Use /forge-task when requirements or scope need an explicit contract.
170
172
  Use /plan for this feature; do not write code yet.
171
173
  Use /enhance to implement this planned feature.
172
- In Codex, use /prompts:debug for this failing behavior and find the root cause before editing.
174
+ Use /forge-debug for this failing behavior and find the root cause before editing.
173
175
  Use /review before claiming this feature/refactor complete.
174
- In Codex, use /prompts:release for npm versioning and publishing.
176
+ Use /forge-release for npm versioning and publishing.
175
177
  Use $clean-code before editing this module.
176
178
  Use $systematic-debugging to investigate this bug.
177
179
  Use $webapp-testing to verify the UI with Playwright.
@@ -919,18 +921,20 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
919
921
 
920
922
  ## Task Flow
921
923
 
922
- Route every task before editing. In Codex, use \`/prompts:task <request>\`; other clients can read the matching file under \`.agent/workflows/\`.
924
+ Forge is the member-facing command suite. Use \`/forge-task <request>\` in Antigravity, Claude Code, or Cursor, and \`$forge-task <request>\` in Codex. The command classifies the request and continues the selected workflow in the same turn; it must not stop at a member-facing \`NEXT\` command.
923
925
 
924
- - Questions and analysis: answer directly, cite relevant files when useful, and do not edit code.
925
- - Simple fix: use Codex \`/prompts:simple <request>\` only for one-file, unambiguous changes with no behavior or contract change.
926
- - Bug or failing behavior: use Codex \`/prompts:debug <symptom>\` and follow the evidence-first root-cause flow.
927
- - Feature or refactor: use \`/brainstorm\` for discovery, Codex \`/prompts:spec\` for ambiguous or multi-file scope, then \`/plan\`, wait for approval, implement, test, and \`/review\`.
928
- - Pre-merge review: use \`/review\` even when the implementation itself was done by another client or member.
929
- - Release or npm publish: use Codex \`/prompts:release\`; release work never uses the simple fast path.
926
+ - Questions and analysis without a command: answer directly and do not edit code.
927
+ - Edit requests without a command: route internally as \`forge-task\` before editing.
928
+ - Simple fix: use \`/forge-fast <request>\` only for one-file, unambiguous changes with no behavior or contract change.
929
+ - Bug or failing behavior: use \`/forge-debug <symptom>\` and follow the evidence-first root-cause flow.
930
+ - Research: use \`/forge-research <question>\`; research does not edit product code.
931
+ - Feature or refactor: \`forge-task\` handles research/brainstorm, spec, plan approval, implementation, test, and review in sequence.
932
+ - Pre-merge review: use \`/forge-review\` even when implementation was done by another client or member.
933
+ - Release or npm publish: use \`/forge-release\`; release work never uses the fast path.
930
934
  - Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
931
935
  - UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
932
936
 
933
- ### Fast Path (Codex \`/prompts:simple\`)
937
+ ### Fast Path (Forge \`forge-fast\`)
934
938
 
935
939
  The fast path intentionally bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection, focused verification, or reporting evidence. The agent must state this protocol before editing:
936
940
 
@@ -940,7 +944,7 @@ REASON: [why the change is one-file and unambiguous]
940
944
  SCOPE: [file or narrow area]
941
945
  \`\`\`
942
946
 
943
- If the scope expands, stop and re-route with Codex \`/prompts:task\`. Do not silently skip gates for work that changes behavior, APIs, schemas, security, CI, dependencies, workflows, or release state.
947
+ If the scope expands, stop and internally re-route through \`forge-task\`. Do not silently skip gates for work that changes behavior, APIs, schemas, security, CI, dependencies, workflows, or release state.
944
948
 
945
949
  ### Gated Flow (feature or refactor)
946
950
 
@@ -949,7 +953,7 @@ If the scope expands, stop and re-route with Codex \`/prompts:task\`. Do not sil
949
953
  3. **Implement** — smallest coherent change per the approved plan, with focused tests for changed behavior.
950
954
  4. **Review** — run \`.agent/workflows/review.md\` (five-axis review) before the change is considered done. All 🔴 BLOCKING items must be resolved or explicitly accepted with rationale.
951
955
 
952
- A feature/refactor task is not "done" until step 4's exit criteria are met — passing tests alone does not satisfy the gate. Simple fixes use the explicit Codex \`/prompts:simple\` fast path above. See \`.agent/docs/getting-started.md\` for the complete route guide.
956
+ A feature/refactor task is not "done" until step 4's exit criteria are met — passing tests alone does not satisfy the gate. Simple fixes use the explicit \`forge-fast\` path above. See \`.agent/docs/getting-started.md\` for the complete route guide.
953
957
 
954
958
  ## Skill Loading
955
959
 
@@ -1183,9 +1187,9 @@ function generateWorkflowDoc() {
1183
1187
 
1184
1188
  ## Before Every Task
1185
1189
 
1186
- 1. Read AGENTS.md.
1187
- 2. Read .agent/docs/project.md.
1188
- 3. Route the request with Codex \`/prompts:task <request>\` when the path is not obvious; otherwise read \`.agent/workflows/task.md\` directly.
1190
+ 1. Read AGENTS.md.
1191
+ 2. Read .agent/docs/project.md.
1192
+ 3. Use \`/forge-task <request>\` (or \`$forge-task <request>\` in Codex) when the request changes code and the path is not obvious.
1189
1193
  4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
1190
1194
  5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
1191
1195
 
@@ -1194,11 +1198,12 @@ function generateWorkflowDoc() {
1194
1198
  | Situation | Command | Workflow / gate |
1195
1199
  |---|---|---|
1196
1200
  | Question or analysis only | direct answer | no edits |
1197
- | One obvious local fix | Codex \`/prompts:simple\` | \`.agent/workflows/simple.md\`, fast-path |
1198
- | Bug, regression, failing test, or unknown error | Codex \`/prompts:debug\` | \`.agent/workflows/debug.md\`, evidence-first |
1199
- | New behavior, multi-file change, or unclear scope | \`/brainstorm\` -> Codex \`/prompts:spec\` when needed -> \`/plan\` | spec/plan approval -> implement -> review |
1200
- | Pre-merge review | \`/review\` | \`.agent/workflows/review.md\`, five-axis |
1201
- | npm version, tag, publish, or deployment | Codex \`/prompts:release\` | \`.agent/workflows/release.md\`, release gate |
1201
+ | One obvious local fix | \`/forge-fast\` | \`.agent/workflows/simple.md\`, fast-path |
1202
+ | Bug, regression, failing test, or unknown error | \`/forge-debug\` | \`.agent/workflows/debug.md\`, evidence-first |
1203
+ | Research request | \`/forge-research\` | evidence report, no edits |
1204
+ | New behavior, multi-file change, or unclear scope | \`/forge-task\` | research/spec/plan approval -> implement -> review |
1205
+ | Pre-merge review | \`/forge-review\` | \`.agent/workflows/review.md\`, five-axis |
1206
+ | npm version, tag, publish, or deployment | \`/forge-release\` | \`.agent/workflows/release.md\`, release gate |
1202
1207
  | Several specialist domains | \`/orchestrate\` | plan -> approval -> parallel work -> integration verify |
1203
1208
 
1204
1209
  If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
@@ -1216,7 +1221,7 @@ If a task is not clearly simple, use the standard flow. Never use the fast path
1216
1221
 
1217
1222
  ## Implementation Flow
1218
1223
 
1219
- For Codex \`/prompts:simple\` fixes, state the fast-path decision before editing:
1224
+ For \`/forge-fast\` fixes, state the fast-path decision before editing:
1220
1225
 
1221
1226
  \`\`\`text
1222
1227
  FAST_PATH: simple-fix
@@ -1233,7 +1238,7 @@ Then:
1233
1238
  5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
1234
1239
  6. Summarize changed files and verification evidence.
1235
1240
 
1236
- For bugs, use Codex \`/prompts:debug\` with \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
1241
+ For bugs, use \`/forge-debug\` with \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
1237
1242
 
1238
1243
  For features or refactors, this flow runs *inside* the gated flow defined in AGENTS.md (spec -> plan -> implement -> review) — steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory \`.agent/workflows/review.md\` gate.
1239
1244
 
@@ -1241,7 +1246,7 @@ For features or refactors, this flow runs *inside* the gated flow defined in AGE
1241
1246
 
1242
1247
  A feature/refactor task is only complete when all of the following hold — not when code compiles or tests pass:
1243
1248
 
1244
- The Spec checkbox may be skipped only when the documented Codex \`/prompts:simple\` fast-path protocol is stated and its criteria are met.
1249
+ The Spec checkbox may be skipped only when the documented \`/forge-fast\` protocol is stated and its criteria are met.
1245
1250
 
1246
1251
  - [ ] \`.agent/workflows/spec.md\` exit criteria met (or explicitly skipped as a trivial/self-contained change)
1247
1252
  - [ ] \`.agent/workflows/plan.md\` produced a plan file, approved by the user
@@ -1265,28 +1270,30 @@ function generateGettingStartedDoc() {
1265
1270
 
1266
1271
  Read this after \`thachvd-kit init\`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
1267
1272
 
1268
- ## Client Command Map
1273
+ ## Forge Command Map
1269
1274
 
1270
- | Client | Task router | Simple fix | Bug fix | Feature spec | Release |
1271
- |---|---|---|---|---|---|
1272
- | Codex | \`/prompts:task\` | \`/prompts:simple\` | \`/prompts:debug\` | \`/prompts:spec\` | \`/prompts:release\` |
1273
- | Antigravity | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
1274
- | Claude Code | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
1275
- | Cursor | \`/task\` | \`/simple\` | \`/debug\` | \`/spec\` | \`/release\` |
1275
+ | Client | Task | Fast | Debug | Research | Review | Release |
1276
+ |---|---|---|---|---|---|---|
1277
+ | Codex | \`$forge-task\` | \`$forge-fast\` | \`$forge-debug\` | \`$forge-research\` | \`$forge-review\` | \`$forge-release\` |
1278
+ | Antigravity | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
1279
+ | Claude Code | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
1280
+ | Cursor | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
1276
1281
 
1277
- Codex reads custom prompts from \`~/.codex/prompts\`. Antigravity reads workspace workflows from \`.agent/workflows\`. Claude Code reads project skills from \`.claude/skills/<name>/SKILL.md\`. Cursor reads commands from \`.cursor/commands\`.
1282
+ Forge commands accept free-form text after the command and continue the selected workflow in the same turn. Plain questions remain normal chat; edit requests without a command are implicitly routed as \`forge-task\`.
1278
1283
 
1279
- ## Start Every Task With The Router
1284
+ Codex Forge skills live in \`~/.codex/skills/forge-*/SKILL.md\`. Antigravity Forge workflows live in \`.agent/workflows/forge-*.md\`. Claude Code Forge commands live in \`.claude/commands/forge-*.md\`. Cursor Forge commands live in \`.cursor/commands/forge-*.md\`.
1280
1285
 
1281
- In Codex, use \`/prompts:task <request>\` before editing whenever the route is not already obvious. Other clients can read \`.agent/workflows/task.md\` directly. It must produce:
1286
+ ## Start Every Task With Forge
1287
+
1288
+ Use the matching Forge command before editing whenever the request is not a simple question. \`forge-task\` must route internally and continue; it must not stop by asking the member to type a second command.
1282
1289
 
1283
1290
  \`\`\`text
1284
- ROUTE: question | simple | feature | bug | review | release | multi-domain
1291
+ ROUTE: question | fast | feature | bug | research | review | release | multi-domain
1285
1292
  WORKFLOW: [exact .agent/workflows/<name>.md file]
1286
1293
  SKILLS: [matching skills, or none]
1287
1294
  AGENTS: [matching specialist agents, or none]
1288
- GATE: fast-path | standard
1289
- NEXT: [the next command or action]
1295
+ GATE: fast-path | standard | human-approval
1296
+ ACTION: [what the agent is doing next in this turn]
1290
1297
  \`\`\`
1291
1298
 
1292
1299
  A workflow is the process and its gates. A skill is the method or checklist. An agent is the specialist role. Chat alone is not a route: the member must select the route and invoke the matching workflow or explicitly choose the question path.
@@ -1296,22 +1303,23 @@ A workflow is the process and its gates. A skill is the method or checklist. An
1296
1303
  | Situation | Command | Gate | Required next step |
1297
1304
  |---|---|---|---|
1298
1305
  | Explain, inspect, or brainstorm only | direct answer or \`/brainstorm\` | none | no code until the request becomes actionable |
1299
- | One obvious local fix | \`/prompts:simple <request>\` in Codex | fast-path | inspect -> edit -> focused verify |
1300
- | New behavior, multi-file change, unclear scope, or >~30 min | \`/prompts:task\` -> \`/brainstorm\` -> \`/prompts:spec\` when needed -> \`/plan\` | standard | wait for approval before implementation |
1301
- | Bug, regression, failing test, or unknown error | \`/prompts:debug <symptom>\` in Codex | bug | reproduce -> isolate -> regression test -> fix -> verify |
1302
- | Pre-merge or independent review | \`/review\` | review | five-axis review; resolve blocking findings |
1303
- | Version, tag, npm publish, or deployment | \`/prompts:release\` in Codex | release | release checklist; never fast-path |
1306
+ | One obvious local fix | \`/forge-fast <request>\` | fast-path | inspect -> edit -> focused verify |
1307
+ | New behavior, multi-file change, unclear scope, or >~30 min | \`/forge-task <request>\` | standard | route -> research/spec/plan -> approval when required -> continue |
1308
+ | Bug, regression, failing test, or unknown error | \`/forge-debug <symptom>\` | bug | reproduce -> isolate -> regression test -> fix -> verify |
1309
+ | Research request | \`/forge-research <question>\` | research | evidence report, no edits |
1310
+ | Pre-merge or independent review | \`/forge-review\` | review | five-axis review; resolve blocking findings |
1311
+ | Version, tag, npm publish, or deployment | \`/forge-release\` | release | release checklist; never fast-path |
1304
1312
  | Frontend + backend + data/security together | \`/orchestrate\` | standard | plan -> approval -> specialist work -> integration verify |
1305
1313
 
1306
1314
  ## Standard Feature Flow
1307
1315
 
1308
- The gated sequence is Spec -> Plan -> Implement -> Review: \`/prompts:task\` -> \`/brainstorm\` -> \`/prompts:spec\` when scope is ambiguous or multi-file -> \`/plan\` -> user approves the plan -> implementation -> \`/test\` -> \`/review\` -> final verification -> commit/push.
1316
+ The gated sequence is Spec -> Plan -> Implement -> Review. \`/forge-task\` manages this sequence internally and pauses only at the explicit user approval gate before implementation.
1309
1317
 
1310
1318
  The plan is a gate, not a suggestion. Do not start product-code implementation before explicit approval. Load only the relevant specialist agent and skills, such as \`$frontend-design\`, \`$api-design\`, or \`$webapp-testing\`.
1311
1319
 
1312
1320
  ## Bug Fix Flow
1313
1321
 
1314
- Use Codex \`/prompts:debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
1322
+ Use \`/forge-debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
1315
1323
 
1316
1324
  1. Capture the exact symptom, environment, reproduction, and expected result.
1317
1325
  2. Inspect the relevant code path with MCP/codegraph when available.
@@ -1325,7 +1333,7 @@ Load \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`
1325
1333
 
1326
1334
  ## Simple Fast Path
1327
1335
 
1328
- Use Codex \`/prompts:simple <request>\` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
1336
+ Use \`/forge-fast <request>\` only when the change is one obvious file, the result is unambiguous, and it changes no behavior, API, schema, security, CI, dependency, workflow, or release contract. Before editing, state:
1329
1337
 
1330
1338
  \`\`\`text
1331
1339
  FAST_PATH: simple-fix
@@ -1333,18 +1341,18 @@ REASON: [why Spec/Plan/Review are not needed]
1333
1341
  SCOPE: [file or narrow area]
1334
1342
  \`\`\`
1335
1343
 
1336
- This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route with Codex \`/prompts:task\`.
1344
+ This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection, focused verification, or reporting evidence. If the scope expands, stop and re-route internally through \`forge-task\`.
1337
1345
 
1338
1346
  ## Command And Skill Map
1339
1347
 
1340
1348
  - \`/brainstorm\`: clarify intent and tradeoffs; no code.
1341
- - Codex \`/prompts:spec\`: define requirements and acceptance criteria; no code.
1349
+ - \`forge-research\`: evidence-based codebase/technical/domain research; no product-code edits.
1342
1350
  - \`/plan\`: create an approved implementation plan; no code before approval.
1343
1351
  - \`/enhance\` or \`/create\`: implement an approved feature with the relevant specialist agent.
1344
- - Codex \`/prompts:debug\`: systematic root-cause investigation and regression protection.
1352
+ - \`forge-debug\`: systematic root-cause investigation and regression protection.
1345
1353
  - \`/test\`: add or run tests and assess coverage.
1346
1354
  - \`/review\`: five-axis review before completion or merge.
1347
- - Codex \`/prompts:release\`: verify, version, tag, publish, and verify npm output.
1355
+ - \`forge-release\`: verify, version, tag, publish, and verify npm output.
1348
1356
  - \`$clean-code\` and \`$verification-before-completion\`: default implementation hygiene.
1349
1357
  - \`$webapp-testing\`: browser/UI verification; use Playwright when available.
1350
1358
 
@@ -1639,6 +1647,65 @@ function copyClientWorkflowCommands() {
1639
1647
  }
1640
1648
  return { claude, cursor, prompts };
1641
1649
  }
1650
+
1651
+ function stripFrontmatter(content) {
1652
+ return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trimStart();
1653
+ }
1654
+
1655
+ function copyForgeCommands() {
1656
+ const srcCommands = path.join(sourceDir, 'commands');
1657
+ const codexSkillsDir = homePath('.codex', 'skills');
1658
+ if (!fs.existsSync(srcCommands)) {
1659
+ return { antigravity: 0, claude: 0, cursor: 0, codex: 0, commands: [] };
1660
+ }
1661
+
1662
+ const destinations = {
1663
+ antigravity: path.join(targetDir, '.agent', 'workflows'),
1664
+ claude: path.join(targetDir, '.claude', 'commands'),
1665
+ cursor: path.join(targetDir, '.cursor', 'commands')
1666
+ };
1667
+ let antigravity = 0;
1668
+ let claude = 0;
1669
+ let cursor = 0;
1670
+ let codex = 0;
1671
+ const commands = [];
1672
+
1673
+ for (const commandName of FORGE_COMMANDS) {
1674
+ const filename = `${commandName}.md`;
1675
+ const sourcePath = path.join(srcCommands, filename);
1676
+ if (!fs.existsSync(sourcePath)) continue;
1677
+ const sourceContent = fs.readFileSync(sourcePath, 'utf8');
1678
+ const body = stripFrontmatter(sourceContent);
1679
+
1680
+ fs.mkdirSync(destinations.antigravity, { recursive: true });
1681
+ fs.copyFileSync(sourcePath, path.join(destinations.antigravity, filename));
1682
+ antigravity++;
1683
+
1684
+ fs.mkdirSync(destinations.claude, { recursive: true });
1685
+ fs.copyFileSync(sourcePath, path.join(destinations.claude, filename));
1686
+ claude++;
1687
+
1688
+ fs.mkdirSync(destinations.cursor, { recursive: true });
1689
+ fs.writeFileSync(path.join(destinations.cursor, filename), body, 'utf8');
1690
+ cursor++;
1691
+
1692
+ if (codexSkillsDir) {
1693
+ const skillDir = path.join(codexSkillsDir, commandName);
1694
+ fs.mkdirSync(skillDir, { recursive: true });
1695
+ const skillBody = body.replace(/\$ARGUMENTS/g, 'the request supplied with this skill');
1696
+ fs.writeFileSync(
1697
+ path.join(skillDir, 'SKILL.md'),
1698
+ `---\nname: ${commandName}\ndescription: ${sourceContent.match(/^description:\s*(.+)$/m)?.[1] || `Run ${commandName}`}\n---\n\nThis skill is invoked as $${commandName}. Treat the user's text supplied with the skill as the request.\n\n${skillBody}`,
1699
+ 'utf8'
1700
+ );
1701
+ codex++;
1702
+ }
1703
+
1704
+ commands.push(commandName);
1705
+ }
1706
+
1707
+ return { antigravity, claude, cursor, codex, commands };
1708
+ }
1642
1709
 
1643
1710
  async function writeGeneratedFile(relativePath, content, assumeYes) {
1644
1711
  const outputPath = path.join(targetDir, relativePath);
@@ -1983,9 +2050,14 @@ async function main() {
1983
2050
  console.log(` ${pc.green('OK')} Installed Codex custom prompts in ${pc.bold('~/.codex/prompts/')} (${codexPrompts.prompts.map(name => `/prompts:${name}`).join(', ')})`);
1984
2051
  }
1985
2052
 
1986
- const clientCommands = copyClientWorkflowCommands();
1987
- if (clientCommands.claude > 0 || clientCommands.cursor > 0) {
1988
- console.log(` ${pc.green('OK')} Installed workflow commands for Claude Code (${clientCommands.claude}) and Cursor (${clientCommands.cursor})`);
2053
+ const legacyClientCommands = copyClientWorkflowCommands();
2054
+ if (legacyClientCommands.claude > 0 || legacyClientCommands.cursor > 0) {
2055
+ console.log(` ${pc.dim('~')} Preserved legacy workflow aliases for Claude Code and Cursor (${legacyClientCommands.claude}/${legacyClientCommands.cursor})`);
2056
+ }
2057
+
2058
+ const forgeCommands = copyForgeCommands();
2059
+ if (forgeCommands.commands.length > 0) {
2060
+ console.log(` ${pc.green('OK')} Installed Forge commands (${forgeCommands.commands.join(', ')}) for Antigravity (${forgeCommands.antigravity}), Claude Code (${forgeCommands.claude}), Cursor (${forgeCommands.cursor}), and Codex skills (${forgeCommands.codex})`);
1989
2061
  }
1990
2062
 
1991
2063
 
@@ -2033,10 +2105,12 @@ async function main() {
2033
2105
  - ${pc.bold('.agent/docs/')} scan-based project rules, including ${pc.bold('getting-started.md')} (standard flow vs fast path)
2034
2106
  - ${pc.bold('.agent/')} skills, workflows, agents, and rules
2035
2107
  - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
2036
- - ${pc.bold('~/.codex/prompts/')} Codex custom prompts (visible as /prompts:<name> after restart)
2108
+ - ${pc.bold('~/.codex/skills/forge-*/')} Forge Codex skills (visible as $forge-task, $forge-fast, and related skills)
2109
+ - ${pc.bold('~/.codex/prompts/')} legacy Codex prompts retained for compatibility
2037
2110
  - ${pc.bold('.claude/skills/')} selected Claude Code native skills
2038
- - ${pc.bold('.claude/skills/{task,simple,debug,spec,release}/')} workflow skills (visible as /task, /simple, /debug, /spec, /release)
2039
- - ${pc.bold('.cursor/commands/')} Cursor workflow commands (visible as /task, /simple, /debug, /spec, /release)
2111
+ - ${pc.bold('.claude/commands/forge-*.md')} Forge Claude Code commands (visible as /forge-task and related commands)
2112
+ - ${pc.bold('.cursor/commands/forge-*.md')} Forge Cursor commands (visible as /forge-task and related commands)
2113
+ - ${pc.bold('.agent/workflows/forge-*.md')} Forge Antigravity workflows (visible as /forge-task and related commands)
2040
2114
  - ${pc.bold('.claude/settings.json')} Definition-of-Done Stop hook (Claude Code only — blocks reporting a feature/refactor "done" without a plan + review pass)
2041
2115
 
2042
2116
  ${pc.bold('MCP/tooling setup:')}
package/commands/forge-debug.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Investigate and fix a bug with evidence-first root-cause analysis.
3
+ argument-hint: [SYMPTOM]
4
+ ---
5
+
6
+ # Forge Debug
7
+
8
+ Symptom:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/debug.md`, use `$systematic-debugging`, the `debugger` agent, and `testing-patterns` when available. Reproduce the symptom, inspect the relevant code path with codegraph/MCP, form and test hypotheses, identify the root cause, add regression protection when practical, make the smallest fix, and verify it. Do not patch by guesswork and do not stop by asking the member to invoke another command.
package/commands/forge-fast.md ADDED
@@ -0,0 +1,22 @@
1
+ ---
2
+ description: Execute a trivial, unambiguous change with focused verification.
3
+ argument-hint: [REQUEST]
4
+ ---
5
+
6
+ # Forge Fast Path
7
+
8
+ Request:
9
+
10
+ $ARGUMENTS
11
+
12
+ Use this path only for one obvious file or tiny local change with no behavior, API, schema, security, CI, dependency, workflow, or release contract change.
13
+
14
+ Before editing, state exactly:
15
+
16
+ ```text
17
+ FAST_PATH: simple-fix
18
+ REASON: [why Spec, Plan, and feature Review are not needed]
19
+ SCOPE: [file or narrow area]
20
+ ```
21
+
22
+ Inspect the target, make the smallest change, run focused verification, and report evidence. If the scope expands, stop and internally re-route through the appropriate Forge workflow. Never skip inspection or verification.
package/commands/forge-release.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Verify, version, publish, and verify the thachvd-kit npm release.
3
+ argument-hint: [RELEASE_REQUEST]
4
+ ---
5
+
6
+ # Forge Release
7
+
8
+ Release request:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/release.md` and run the release gate. Confirm the working tree, review status, version, npm authentication, verification output, and package contents before publishing. Never use the fast path. Do not run `npm publish` until the release gate is satisfied and the human has confirmed the final version and publish action. After publishing, verify the registry version and the installed package output.
package/commands/forge-research.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ description: Research the codebase, technical topic, or domain without editing product code.
3
+ argument-hint: [QUESTION]
4
+ ---
5
+
6
+ # Forge Research
7
+
8
+ Research question:
9
+
10
+ $ARGUMENTS
11
+
12
+ Do not edit product code. First classify the research as codebase, external technical, or domain research. For codebase research, use codegraph/MCP first. For external research, use authoritative current sources only when needed and cite them. Return exactly:
13
+
14
+ ```text
15
+ RESEARCH_STATUS: complete | blocked
16
+ QUESTION: [what was investigated]
17
+ ASSUMPTIONS: [explicit assumptions]
18
+ FINDINGS: [evidence-based findings]
19
+ SOURCES: [file paths, symbols, MCP evidence, or URLs]
20
+ RISKS: [known risks and unknowns]
21
+ OPTIONS: [possible approaches and tradeoffs]
22
+ RECOMMENDATION: [recommended direction]
23
+ OPEN_QUESTIONS: [unresolved questions]
24
+ ```
package/commands/forge-review.md ADDED
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: Review a change across correctness, simplicity, architecture, security, and performance.
3
+ argument-hint: [SCOPE]
4
+ ---
5
+
6
+ # Forge Review
7
+
8
+ Review scope:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `.agent/workflows/review.md` and inspect the relevant diff, task, and verification evidence. Review all five axes. Report findings first, ordered by severity, using `BLOCKING`, `SUGGESTION`, `NIT`, or `QUESTION`. Do not edit code during review unless the member explicitly asks for fixes after the findings.
package/commands/forge-task.md ADDED
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: Route a request and continue the selected Forge workflow in this turn.
3
+ argument-hint: [REQUEST]
4
+ ---
5
+
6
+ # Forge Task Orchestrator
7
+
8
+ The request supplied with this command is:
9
+
10
+ $ARGUMENTS
11
+
12
+ Read `AGENTS.md`, `.agent/docs/project.md`, and `.agent/docs/workflow.md` before editing.
13
+
14
+ Classify the request internally as `question`, `fast`, `feature`, `bug`, `research`, `review`, `release`, or `multi-domain`. Then continue the selected workflow in this same turn. Do not stop after printing a `NEXT` command and do not ask the member to invoke another Forge command for ordinary routing.
15
+
16
+ Use this compact status header when useful:
17
+
18
+ ```text
19
+ REQUEST: [original request]
20
+ ROUTE: [route]
21
+ WORKFLOW: [exact workflow file]
22
+ SKILLS: [matching skills]
23
+ AGENTS: [matching agents]
24
+ GATE: fast-path | standard | human-approval
25
+ ACTION: [what you are doing now]
26
+ ```
27
+
28
+ Rules:
29
+
30
+ - Questions and analysis: answer directly with no edits.
31
+ - Trivial one-file changes: apply the `forge-fast` protocol, including focused verification.
32
+ - Bugs or unknown failures: reproduce, isolate root cause, add regression protection, fix, and verify.
33
+ - Research: use codegraph/MCP first for repository questions, use authoritative external sources when needed, and do not edit code.
34
+ - Features and refactors: follow spec -> plan -> approval -> implement -> test -> review. Stop only at the documented human approval gate.
35
+ - Reviews: run the five-axis review and report findings first.
36
+ - Releases: follow `.agent/workflows/release.md`; never use the fast path.
37
+ - If the request is empty or unsafe to classify, ask one concise clarification question.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "thachvd-kit",
3
- "version": "1.0.28",
3
+ "version": "1.0.29",
4
4
  "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
5
5
  "bin": {
6
6
  "thachvd-kit": "./bin/cli.js"
@@ -9,6 +9,7 @@
9
9
  ".agent",
10
10
  "agents",
11
11
  "bin",
12
+ "commands",
12
13
  "kit",
13
14
  "rules",
14
15
  "scripts",