busya
994c0c3e5d
Introduce a UX reference stage to ensure technical plans align with user experience goals. Adds a new template, a generation step in the specification workflow, and mandatory validation checks during planning to prevent technical compromises from degrading the defined user experience.
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
---
|
|
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
|
|
handoffs:
|
|
- label: Create Tasks
|
|
agent: speckit.tasks
|
|
prompt: Break the plan into tasks
|
|
send: true
|
|
- label: Create Checklist
|
|
agent: speckit.checklist
|
|
prompt: Create a checklist for the following domain...
|
|
---
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
## Outline
|
|
|
|
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
|
|
|
|
2. **Load context**: Read FEATURE_SPEC, `ux_reference.md`, `semantic_protocol.md` and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
|
|
|
|
3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
|
|
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
|
|
- Fill Constitution Check section from constitution
|
|
- Evaluate gates (ERROR if violations unjustified)
|
|
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
|
|
- Phase 1: Generate data-model.md, contracts/, quickstart.md
|
|
- Phase 1: Update agent context by running the agent script
|
|
- Re-evaluate Constitution Check post-design
|
|
|
|
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
|
|
|
|
## Phases
|
|
|
|
### Phase 0: Outline & Research
|
|
|
|
1. **Extract unknowns from Technical Context** above:
|
|
- For each NEEDS CLARIFICATION → research task
|
|
- For each dependency → best practices task
|
|
- For each integration → patterns task
|
|
|
|
2. **Generate and dispatch research agents**:
|
|
|
|
```text
|
|
For each unknown in Technical Context:
|
|
Task: "Research {unknown} for {feature context}"
|
|
For each technology choice:
|
|
Task: "Find best practices for {tech} in {domain}"
|
|
```
|
|
|
|
3. **Consolidate findings** in `research.md` using format:
|
|
- Decision: [what was chosen]
|
|
- Rationale: [why chosen]
|
|
- Alternatives considered: [what else evaluated]
|
|
|
|
**Output**: research.md with all NEEDS CLARIFICATION resolved
|
|
|
|
### Phase 1: Design & Contracts
|
|
|
|
**Prerequisites:** `research.md` complete
|
|
|
|
0. **Validate Design against UX Reference**:
|
|
- Check if the proposed architecture supports the latency, interactivity, and flow defined in `ux_reference.md`.
|
|
- **CRITICAL**: If the technical plan requires compromising the UX defined in `ux_reference.md` (e.g. "We can't do real-time validation because X"), you **MUST STOP** and warn the user. Do not proceed until resolved.
|
|
|
|
1. **Extract entities from feature spec** → `data-model.md`:
|
|
- Entity name, fields, relationships
|
|
- Validation rules from requirements
|
|
- State transitions if applicable
|
|
|
|
2. **Define Module & Function Contracts (Semantic Protocol)**:
|
|
- **MANDATORY**: For every new module, define the [DEF] Header and Module-level Contract (@TIER, @PURPOSE, @INVARIANT) as per `semantic_protocol.md`.
|
|
- **REQUIRED**: Define Function Contracts (@PRE, @POST) for critical logic.
|
|
- Output specific contract definitions to `contracts/modules.md` or append to `data-model.md` to guide implementation.
|
|
- Ensure strict adherence to `semantic_protocol.md` syntax.
|
|
|
|
3. **Generate API contracts** from functional requirements:
|
|
- For each user action → endpoint
|
|
- Use standard REST/GraphQL patterns
|
|
- Output OpenAPI/GraphQL schema to `/contracts/`
|
|
|
|
3. **Agent context update**:
|
|
- Run `.specify/scripts/bash/update-agent-context.sh kilocode`
|
|
- These scripts detect which AI agent is in use
|
|
- Update the appropriate agent-specific context file
|
|
- Add only new technology from current plan
|
|
- Preserve manual additions between markers
|
|
|
|
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
|
|
|
|
## Key rules
|
|
|
|
- Use absolute paths
|
|
- ERROR on gate failures or unresolved clarifications
|