Skip to content

Commit 48d8b20

Browse files
johnmbaughmanjohnmbaughman
committed
chore(specs): add parameter-sets spec and feature artifacts
1 parent c9fd2fd commit 48d8b20

6 files changed

Lines changed: 537 additions & 0 deletions

File tree

‎specs/002-parameter-sets/data-model.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# data-model.md — ParameterSet enhancement for Install-SpecKitTemplate
2+
3+
Date: 2025-10-02
4+
Spec source: `C:\Personal\Files\source\repos\PSSpecKit\specs\feat\paramsets-install-speckit\spec.md`
5+
6+
## Entities
7+
8+
1. RunContext
9+
- id: string (UUID)
10+
- Timestamp: datetime
11+
- Mode: enum {Interactive, Noninteractive}
12+
- IsTty: boolean
13+
- ExitCode: integer
14+
15+
2. Parameters
16+
- Agent: string (required in Noninteractive or prompted in Interactive)
17+
- Shell: enum {ps, sh}
18+
- Version: string (tag or "latest")
19+
- Path: string (filesystem path)
20+
- Force: boolean
21+
- SaveZip: boolean (default: false)
22+
- Retry: integer (default: 0)
23+
24+
3. OverwriteDecision
25+
- Targets: array of string (paths)
26+
- Decision: enum {Yes, YesToAll, No, NoToAll}
27+
- Timestamp: datetime
28+
29+
## Relationships
30+
- RunContext has one Parameters
31+
- RunContext may have zero or one OverwriteDecision
32+
33+
## Validation Rules
34+
- If Mode == Interactive, IsTty must be true else exit code 2
35+
- If Mode == Noninteractive, no prompts allowed
36+
- Retry must be >= 0
37+
- Agent and Shell must be non-empty strings when required
38+
39+
## Notes
40+
- Keep the data model small; it's primarily used to generate tests and structure code paths.

‎specs/002-parameter-sets/plan.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
2+
# Implementation Plan: [FEATURE]
3+
4+
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
5+
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
6+
7+
## Execution Flow (/plan command scope)
8+
```
9+
1. Load feature spec from Input path
10+
→ If not found: ERROR "No feature spec at {path}"
11+
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
12+
→ Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
13+
→ Set Structure Decision based on project type
14+
3. Fill the Constitution Check section based on the content of the constitution document.
15+
4. Evaluate Constitution Check section below
16+
→ If violations exist: Document in Complexity Tracking
17+
→ If no justification possible: ERROR "Simplify approach first"
18+
→ Update Progress Tracking: Initial Constitution Check
19+
5. Execute Phase 0 → research.md
20+
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
21+
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
22+
7. Re-evaluate Constitution Check section
23+
→ If new violations: Refactor design, return to Phase 1
24+
→ Update Progress Tracking: Post-Design Constitution Check
25+
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
26+
9. STOP - Ready for /tasks command
27+
```
28+
29+
**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
30+
- Phase 2: /tasks command creates tasks.md
31+
- Phase 3-4: Implementation execution (manual or via tools)
32+
33+
## Summary
34+
[Extract from feature spec: primary requirement + technical approach from research]
35+
36+
## Technical Context
37+
**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
38+
**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
39+
**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
40+
**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
41+
**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
42+
**Project Type**: [single/web/mobile - determines source structure]
43+
**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
44+
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
45+
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
46+
47+
## Constitution Check
48+
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
49+
50+
[Gates determined based on constitution file]
51+
52+
## Project Structure
53+
54+
### Documentation (this feature)
55+
```
56+
specs/[###-feature]/
57+
├── plan.md # This file (/plan command output)
58+
├── research.md # Phase 0 output (/plan command)
59+
├── data-model.md # Phase 1 output (/plan command)
60+
├── quickstart.md # Phase 1 output (/plan command)
61+
├── contracts/ # Phase 1 output (/plan command)
62+
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
63+
```
64+
65+
### Source Code (repository root)
66+
<!--
67+
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
68+
for this feature. Delete unused options and expand the chosen structure with
69+
real paths (e.g., apps/admin, packages/something). The delivered plan must
70+
not include Option labels.
71+
-->
72+
```
73+
# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
74+
src/
75+
├── models/
76+
├── services/
77+
├── cli/
78+
└── lib/
79+
80+
tests/
81+
├── contract/
82+
├── integration/
83+
└── unit/
84+
85+
# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
86+
backend/
87+
├── src/
88+
│ ├── models/
89+
│ ├── services/
90+
│ └── api/
91+
└── tests/
92+
93+
frontend/
94+
├── src/
95+
│ ├── components/
96+
│ ├── pages/
97+
│ └── services/
98+
└── tests/
99+
100+
# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
101+
api/
102+
└── [same as backend above]
103+
104+
ios/ or android/
105+
└── [platform-specific structure: feature modules, UI flows, platform tests]
106+
```
107+
108+
**Structure Decision**: [Document the selected structure and reference the real
109+
directories captured above]
110+
111+
## Phase 0: Outline & Research
112+
1. **Extract unknowns from Technical Context** above:
113+
- For each NEEDS CLARIFICATION → research task
114+
- For each dependency → best practices task
115+
- For each integration → patterns task
116+
117+
2. **Generate and dispatch research agents**:
118+
```
119+
For each unknown in Technical Context:
120+
Task: "Research {unknown} for {feature context}"
121+
For each technology choice:
122+
Task: "Find best practices for {tech} in {domain}"
123+
```
124+
125+
3. **Consolidate findings** in `research.md` using format:
126+
- Decision: [what was chosen]
127+
- Rationale: [why chosen]
128+
- Alternatives considered: [what else evaluated]
129+
130+
**Output**: research.md with all NEEDS CLARIFICATION resolved
131+
132+
## Phase 1: Design & Contracts
133+
*Prerequisites: research.md complete*
134+
135+
1. **Extract entities from feature spec** → `data-model.md`:
136+
- Entity name, fields, relationships
137+
- Validation rules from requirements
138+
- State transitions if applicable
139+
140+
2. **Generate API contracts** from functional requirements:
141+
- For each user action → endpoint
142+
- Use standard REST/GraphQL patterns
143+
- Output OpenAPI/GraphQL schema to `/contracts/`
144+
145+
3. **Generate contract tests** from contracts:
146+
- One test file per endpoint
147+
- Assert request/response schemas
148+
- Tests must fail (no implementation yet)
149+
150+
4. **Extract test scenarios** from user stories:
151+
- Each story → integration test scenario
152+
- Quickstart test = story validation steps
153+
154+
5. **Update agent file incrementally** (O(1) operation):
155+
- Run `.specify/scripts/powershell/update-agent-context.ps1 -AgentType windsurf`
156+
**IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
157+
- If exists: Add only NEW tech from current plan
158+
- Preserve manual additions between markers
159+
- Update recent changes (keep last 3)
160+
- Keep under 150 lines for token efficiency
161+
- Output to repository root
162+
163+
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
164+
165+
## Phase 2: Task Planning Approach
166+
*This section describes what the /tasks command will do - DO NOT execute during /plan*
167+
168+
**Task Generation Strategy**:
169+
- Load `.specify/templates/tasks-template.md` as base
170+
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
171+
- Each contract → contract test task [P]
172+
- Each entity → model creation task [P]
173+
- Each user story → integration test task
174+
- Implementation tasks to make tests pass
175+
176+
**Ordering Strategy**:
177+
- TDD order: Tests before implementation
178+
- Dependency order: Models before services before UI
179+
- Mark [P] for parallel execution (independent files)
180+
181+
**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
182+
183+
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
184+
185+
## Phase 3+: Future Implementation
186+
*These phases are beyond the scope of the /plan command*
187+
188+
**Phase 3**: Task execution (/tasks command creates tasks.md)
189+
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
190+
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
191+
192+
## Complexity Tracking
193+
*Fill ONLY if Constitution Check has violations that must be justified*
194+
195+
| Violation | Why Needed | Simpler Alternative Rejected Because |
196+
|-----------|------------|-------------------------------------|
197+
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
198+
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
199+
200+
201+
## Progress Tracking
202+
*This checklist is updated during execution flow*
203+
204+
**Phase Status**:
205+
- [ ] Phase 0: Research complete (/plan command)
206+
- [ ] Phase 1: Design complete (/plan command)
207+
- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
208+
- [ ] Phase 3: Tasks generated (/tasks command)
209+
- [ ] Phase 4: Implementation complete
210+
- [ ] Phase 5: Validation passed
211+
212+
**Gate Status**:
213+
- [ ] Initial Constitution Check: PASS
214+
- [ ] Post-Design Constitution Check: PASS
215+
- [ ] All NEEDS CLARIFICATION resolved
216+
- [ ] Complexity deviations documented
217+
218+
---
219+
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

‎specs/002-parameter-sets/quickstart.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# quickstart.md — ParameterSet enhancement for Install-SpecKitTemplate
2+
3+
Date: 2025-10-02
4+
Spec source: `C:\Personal\Files\source\repos\PSSpecKit\specs\feat\paramsets-install-speckit\spec.md`
5+
6+
## Examples
7+
8+
### Interactive local run
9+
Run the installer and answer prompts when asked.
10+
11+
pwsh -NoProfile -File tools/Install-SpecKitTemplate.ps1 -Interactive
12+
13+
Expected flow:
14+
- Prompts for missing Agent, Shell, Version, Path, Force
15+
- If files exist, one confirmation prompt: Yes/YesToAll/No/NoToAll
16+
- SaveZip/Retry use defaults unless explicitly provided
17+
18+
### Noninteractive CI run
19+
Supply all parameters on the command line for CI usage.
20+
21+
pwsh -NoProfile -File tools/Install-SpecKitTemplate.ps1 -Agent copilot -Shell ps -Version latest -Force -SaveZip -Retry 3
22+
23+
Expected flow:
24+
- No prompts; script runs to completion or exits with a non-zero code on failure
25+
26+
### Error modes
27+
- Running `-Interactive` in CI (no TTY) should exit with code 2 and a descriptive message
28+
- Supplying incompatible parameters should fail with exit code 3
29+
30+
## Test scenarios
31+
- TTY present: `-Interactive` prompts and proceeds on Yes
32+
- TTY absent: `-Interactive` exits code 2
33+
- Overwrite: detect existing targets, user replies No → exit code 3
34+
- SaveZip behavior: default used in interactive, explicit flag respected
35+

‎specs/002-parameter-sets/research.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# research.md — ParameterSet enhancement for Install-SpecKitTemplate
2+
3+
Date: 2025-10-02
4+
Spec source: `C:\Personal\Files\source\repos\PSSpecKit\specs\feat\paramsets-install-speckit\spec.md`
5+
6+
## Purpose & Goals
7+
- Resolve technical unknowns for implementing two ParameterSets (`Interactive`, `Noninteractive`) in a PowerShell script.
8+
- Produce design decisions, constraints, and recommended implementations that minimize rework and align with the repo constitution.
9+
10+
## Extracted Unknowns / Clarifications (resolved)
11+
- Overwrite confirmation scope: single prompt only when targets exist; includes "Yes to all / No to all".
12+
- Non-TTY behavior for `-Interactive`: fail immediately with exit code 2.
13+
- SaveZip/Retry prompting: do not prompt; use defaults unless provided.
14+
- Parameter-set validation: strict validation; error the run if incompatible parameters supplied.
15+
- Exit codes: 1=general, 2=TTY/interactive, 3=validation/user-decline.
16+
17+
## Technical Context
18+
- Language: PowerShell (pwsh 7+ preferred)
19+
- Testing: Pester v5 (existing helper `tools/run-pester-v5.ps1`)
20+
- Linting: PSScriptAnalyzer (required by constitution)
21+
- Primary files touched: `tools/Install-SpecKitTemplate.ps1`, `tests/*.Tests.ps1`
22+
- Platform: cross-platform (Windows/macOS/Linux) but interactive TTY semantics must be handled portably.
23+
24+
## Decisions & Rationale
25+
1. ParameterSet approach
26+
- Decision: Use PowerShell ParameterSet attributes (`ParameterSetName`) on Param block and function to create `Interactive` and `Noninteractive` sets.
27+
- Rationale: Native cmdlet semantics ensure binding and validation integrate with PowerShell's parameter binder.
28+
29+
2. Interactive prompting behavior
30+
- Decision: Prompt only for missing values when `-Interactive` is present; respect supplied parameters; present overwrite prompt only when targets exist; do not prompt for SaveZip/Retry.
31+
- Rationale: Minimizes surprise; allows scripts to supply some values while enabling interactive confirmation; matches previous clarifications.
32+
33+
3. TTY detection & failure mode
34+
- Decision: Detect TTY via `$Host.UI.RawUI` and fall back to failing with exit code 2 when missing.
35+
- Rationale: Portable and consistent across pwsh hosts in CI.
36+
37+
4. Exit codes
38+
- Decision: Use exit code mapping: 1=general, 2=TTY/interactive, 3=validation/user-decline.
39+
- Rationale: Distinct codes simplify automated tests and CI checks.
40+
41+
5. Safe extraction
42+
- Decision: Extract zip contents into a temp folder, validate artifact integrity, then move into target path; use `Expand-Archive` or `System.IO.Compression.ZipFile` cautiously and validate presence of expected files.
43+
- Rationale: Prevent partial writes and reduce corruption risk on interrupts.
44+
45+
## Risks & Mitigations
46+
- Risk: `$Host.UI.RawUI` not available in some hosts -> Mitigation: check for its presence and class; if missing, treat as non-TTY and error.
47+
- Risk: Tests that mock TTY behavior may be brittle -> Mitigation: centralize TTY check into a small function that tests can mock.
48+
49+
## Next steps (Phase 1 inputs)
50+
- Create `data-model.md` (entities: parameters, run context, exit codes)
51+
- Create `quickstart.md` with example commands and test scenarios
52+
- Enumerate contract/test cases for Pester
53+

0 commit comments

Comments
 (0)