Skip to content

SKILL.md

Latest commit

 

History

History
152 lines (124 loc) · 6.32 KB

SKILL.md

File metadata and controls

152 lines (124 loc) · 6.32 KB
Raw
name spec-forge-intake
description 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.

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 resolve
  • spec-forge-cli apply
  • spec-forge-cli artifact get
  • spec-forge-cli artifact merge
  • spec-forge-cli approve
  • spec-forge-cli init
  • spec-forge-cli gate check
  • spec-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

  1. 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 ....
  2. 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 ...
  3. 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.
  4. 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.
  5. Choose the active discussion roles for this spec. Always keep at least:
    • product-manager
    • ux-architect
    • tech-lead
    • qa-lead
  6. 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
  7. Keep each turn lightweight:
    • no more than 3 tightly related questions
    • no solution deep dive yet
    • no per-component or per-file review yet
  8. 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.
  9. 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.yaml
    • spec-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.
  10. Run:
  • spec-forge-cli gate check --target <target-dir> --spec-id <spec-id> --stage intake --write
  • spec-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.