Spec Forge Intake
Use this stage to turn a rough request into a stable framing contract.
This stage answers: what problem are we solving, for whom, inside what scope,
under what constraints, and through which discussion roles.
Shared Operating Rules
- This skill runs only in Plan mode. If the runtime is not Plan mode, stop and
tell the user to switch before continuing.
- Confirm both chat language and file language before collecting stage-specific
details. Default to the current chat language and English file artifacts only
if the user has no preference.
- Keep decisions in chat. YAML remains the persisted source of truth, but the
user should not need to inspect files to move the stage forward.
- Approvals happen from chat summaries. Summarize the current intake state in
chat, get confirmation there, and then record approval in YAML.
Required Shared CLI Commands
spec-forge-cli resolvespec-forge-cli applyspec-forge-cli artifact getspec-forge-cli artifact mergespec-forge-cli approvespec-forge-cli initspec-forge-cli gate checkspec-forge-cli stage advance
Required UX Contract
Read ../spec-forge/assets/contracts/ux-contracts.yaml
before collecting parameters.
At the start of the stage, run:
spec-forge-cli resolve --target <target-dir> --skill spec-forge-intake --stage intake --write
If the runtime is not Plan mode, stop and ask the user to switch before
collecting inputs or showing any choice dialog.
Use chat summaries as the approval surface; YAML remains the persisted contract
for the stage.
Entry Gate
| # |
Check |
Source |
| 1 |
Target project directory is known |
User or workspace |
| 2 |
.spec-forge/ exists or can be initialized |
Filesystem |
Required Inputs
- The user request
- The target project directory
- Enough context to describe the goal, users, scope, and major constraints
Workflow
- Resolve invocation UX first with:
spec-forge-cli resolve --target <target-dir> --skill spec-forge-intake --stage intake --write
Confirm chat language and file language before stage-specific intake
questions.
Then collect only the next missing parameter, one step at a time, and record
every accepted answer or choice with
spec-forge-cli apply ....
- If
.spec-forge/ or the target spec_id is missing, run:
spec-forge-cli init --target <target-dir> --spec-id <spec-id> --request-title ... --request-summary ...
- Update
.spec-forge/specs/<spec-id>/framing/request-context.yaml.
Prefer spec-forge-cli artifact merge --file framing/request-context.yaml
for artifact-level writes that are not covered by the current apply
parameter or choice.
- Update
.spec-forge/specs/<spec-id>/framing/role-map.yaml.
Prefer spec-forge-cli artifact merge --file framing/role-map.yaml
for artifact-level writes that are not covered by the current apply
parameter or choice.
- Choose the active discussion roles for this spec. Always keep at least:
product-managerux-architecttech-leadqa-lead
- Stay broad. Ask only the highest-leverage framing questions:
- problem and goal
- users and reviewers
- in-scope and out-of-scope boundaries
- product, technical, and delivery constraints
- Keep each turn lightweight:
- no more than 3 tightly related questions
- no solution deep dive yet
- no per-component or per-file review yet
- After each meaningful user answer, update the YAML artifacts instead of
holding the state only in conversation. Prefer
spec-forge-cli apply ... over manual edits
for normal parameter and choice collection, and use
spec-forge-cli artifact merge ... when refining artifact fields outside the
declared UX parameters.
- Present a concise intake summary in chat and ask for explicit approval there.
Do not ask the user to open or review
request-context.yaml or
role-map.yaml.
Use a choice dialog when the runtime supports it; otherwise fall back to a
compact numbered menu.
When the user approves the chat summary, record it with:
spec-forge-cli approve --target <target-dir> --spec-id <spec-id> --file framing/request-context.yamlspec-forge-cli approve --target <target-dir> --spec-id <spec-id> --file framing/role-map.yaml
If the user is not ready to approve, keep the artifact explicit with
spec-forge-cli artifact merge ... and an approval.status such as
pending.
- Run:
spec-forge-cli gate check --target <target-dir> --spec-id <spec-id> --stage intake --writespec-forge-cli stage advance --target <target-dir> --spec-id <spec-id> --stage intake
Outputs
.spec-forge/specs/<spec-id>/framing/request-context.yaml.spec-forge/specs/<spec-id>/framing/role-map.yaml.spec-forge/specs/<spec-id>/gates/intake.yaml
Exit Gate
| # |
Check |
| 1 |
Problem statement is explicit |
| 2 |
Goal is explicit |
| 3 |
In-scope list exists |
| 4 |
Primary users are named |
| 5 |
Active role map exists |
| 6 |
Both intake YAML artifacts are user-approved |
Guardrails
- Do not design the final solution here.
- Do not start journey or component enumeration here.
- Do not discuss detailed code structure here beyond capturing hard constraints.
- Do not overwhelm the user with a giant checklist in one message.
- Do not collect missing required parameters in one large batch.
- Do not continue in non-Plan mode.
- Do not ask the user to inspect YAML files directly. Summarize intake content
in chat instead.
- Do not proceed if approval is ambiguous. Record
approval.status: pending until
the user confirms, using spec-forge-cli artifact merge ... when needed.
Next Step
Continue with
../spec-forge-architecture/SKILL.md.
1---2name: spec-forge-intake3description: Use when you need to turn a rough request into a clear spec framing by defining the problem, stakeholders, scope boundaries, and non-negotiable constraints before solution design begins.4---56# Spec Forge Intake78Use this stage to turn a rough request into a stable framing contract.910This stage answers: what problem are we solving, for whom, inside what scope,11under what constraints, and through which discussion roles.1213## Shared Operating Rules1415- This skill runs only in Plan mode. If the runtime is not Plan mode, stop and16 tell the user to switch before continuing.17- Confirm both chat language and file language before collecting stage-specific18 details. Default to the current chat language and English file artifacts only19 if the user has no preference.20- Keep decisions in chat. YAML remains the persisted source of truth, but the21 user should not need to inspect files to move the stage forward.22- Approvals happen from chat summaries. Summarize the current intake state in23 chat, get confirmation there, and then record approval in YAML.2425## Required Shared CLI Commands2627- `spec-forge-cli resolve`28- `spec-forge-cli apply`29- `spec-forge-cli artifact get`30- `spec-forge-cli artifact merge`31- `spec-forge-cli approve`32- `spec-forge-cli init`33- `spec-forge-cli gate check`34- `spec-forge-cli stage advance`3536## Required UX Contract3738Read [`../spec-forge/assets/contracts/ux-contracts.yaml`](../spec-forge/assets/contracts/ux-contracts.yaml)39before collecting parameters.4041At the start of the stage, run:4243`spec-forge-cli resolve --target <target-dir> --skill spec-forge-intake --stage intake --write`4445If the runtime is not Plan mode, stop and ask the user to switch before46collecting inputs or showing any choice dialog.4748Use chat summaries as the approval surface; YAML remains the persisted contract49for the stage.5051## Entry Gate5253| # | Check | Source |54| --- | ------------------------------------------- | ----------------- |55| 1 | Target project directory is known | User or workspace |56| 2 | `.spec-forge/` exists or can be initialized | Filesystem |5758## Required Inputs5960- The user request61- The target project directory62- Enough context to describe the goal, users, scope, and major constraints6364## Workflow65661. Resolve invocation UX first with:67 `spec-forge-cli resolve --target <target-dir> --skill spec-forge-intake --stage intake --write`68 Confirm chat language and file language before stage-specific intake69 questions.70 Then collect only the next missing parameter, one step at a time, and record71 every accepted answer or choice with72 `spec-forge-cli apply ...`.732. If `.spec-forge/` or the target `spec_id` is missing, run:74 `spec-forge-cli init --target <target-dir> --spec-id <spec-id> --request-title ... --request-summary ...`753. Update `.spec-forge/specs/<spec-id>/framing/request-context.yaml`.76 Prefer `spec-forge-cli artifact merge --file framing/request-context.yaml`77 for artifact-level writes that are not covered by the current `apply`78 parameter or choice.794. Update `.spec-forge/specs/<spec-id>/framing/role-map.yaml`.80 Prefer `spec-forge-cli artifact merge --file framing/role-map.yaml`81 for artifact-level writes that are not covered by the current `apply`82 parameter or choice.835. Choose the active discussion roles for this spec. Always keep at least:84 - `product-manager`85 - `ux-architect`86 - `tech-lead`87 - `qa-lead`886. Stay broad. Ask only the highest-leverage framing questions:89 - problem and goal90 - users and reviewers91 - in-scope and out-of-scope boundaries92 - product, technical, and delivery constraints937. Keep each turn lightweight:94 - no more than 3 tightly related questions95 - no solution deep dive yet96 - no per-component or per-file review yet978. After each meaningful user answer, update the YAML artifacts instead of98 holding the state only in conversation. Prefer99 `spec-forge-cli apply ...` over manual edits100 for normal parameter and choice collection, and use101 `spec-forge-cli artifact merge ...` when refining artifact fields outside the102 declared UX parameters.1039. Present a concise intake summary in chat and ask for explicit approval there.104 Do not ask the user to open or review `request-context.yaml` or105 `role-map.yaml`.106 Use a choice dialog when the runtime supports it; otherwise fall back to a107 compact numbered menu.108 When the user approves the chat summary, record it with:109 - `spec-forge-cli approve --target <target-dir> --spec-id <spec-id> --file framing/request-context.yaml`110 - `spec-forge-cli approve --target <target-dir> --spec-id <spec-id> --file framing/role-map.yaml`111 If the user is not ready to approve, keep the artifact explicit with112 `spec-forge-cli artifact merge ...` and an `approval.status` such as113 `pending`.11410. Run:115116- `spec-forge-cli gate check --target <target-dir> --spec-id <spec-id> --stage intake --write`117- `spec-forge-cli stage advance --target <target-dir> --spec-id <spec-id> --stage intake`118119## Outputs120121- `.spec-forge/specs/<spec-id>/framing/request-context.yaml`122- `.spec-forge/specs/<spec-id>/framing/role-map.yaml`123- `.spec-forge/specs/<spec-id>/gates/intake.yaml`124125## Exit Gate126127| # | Check |128| --- | -------------------------------------------- |129| 1 | Problem statement is explicit |130| 2 | Goal is explicit |131| 3 | In-scope list exists |132| 4 | Primary users are named |133| 5 | Active role map exists |134| 6 | Both intake YAML artifacts are user-approved |135136## Guardrails137138- Do not design the final solution here.139- Do not start journey or component enumeration here.140- Do not discuss detailed code structure here beyond capturing hard constraints.141- Do not overwhelm the user with a giant checklist in one message.142- Do not collect missing required parameters in one large batch.143- Do not continue in non-Plan mode.144- Do not ask the user to inspect YAML files directly. Summarize intake content145 in chat instead.146- Do not proceed if approval is ambiguous. Record `approval.status: pending` until147 the user confirms, using `spec-forge-cli artifact merge ...` when needed.148149## Next Step150151Continue with152[`../spec-forge-architecture/SKILL.md`](../spec-forge-architecture/SKILL.md).
bytelandtechnology