Skip to content

Commit c9151a8

Browse files
MariusStorhaugMariusStorhaug
committed
feat: Update constitution and implementation plan with expanded guidance and requirements
1 parent 0ffc613 commit c9151a8

File tree

2 files changed

+227
-48
lines changed

2 files changed

+227
-48
lines changed

‎.specify/memory/constitution.md‎

Lines changed: 176 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,191 @@
1-
# [PROJECT_NAME] Constitution
2-
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
1+
<!--
2+
Sync Impact Report - Constitution v1.1.0
3+
========================================
4+
Version Change: 1.0.0 → 1.1.0 (MINOR - expanded guidance)
5+
Date: 2025-10-01
6+
7+
Modified Principles:
8+
- Expanded Principle I (Workflow-First Design) with action script requirements
9+
- Enhanced Principle III (Platform Independence) with PowerShell 7.4+ requirement
10+
- Added CI validation workflow requirement to Principle II
11+
12+
Added Sections:
13+
- Technical Constraints (PowerShell version, action-based implementation)
14+
- Workflow Testing Standards (CI vs production workflow distinction)
15+
16+
Removed Sections: None
17+
18+
Templates Status:
19+
✅ plan-template.md - Already aligned with constitution checks
20+
✅ spec-template.md - No changes needed (no constitution-specific requirements)
21+
✅ tasks-template.md - No changes needed (general task structure applies)
22+
23+
Follow-up TODOs:
24+
- TODO(RATIFICATION_DATE): Determine original constitution adoption date
25+
26+
Rationale for MINOR bump:
27+
- Added specific technical requirements (PowerShell 7.4+, action scripts over inline)
28+
- Expanded workflow-first principle with implementation details
29+
- Added CI validation workflow as required testing standard
30+
- Material expansion of existing principles without breaking compatibility
31+
-->
32+
33+
# Process-PSModule Constitution
334

435
## Core Principles
536

6-
### [PRINCIPLE_1_NAME]
7-
<!-- Example: I. Library-First -->
8-
[PRINCIPLE_1_DESCRIPTION]
9-
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
37+
### I. Workflow-First Design (NON-NEGOTIABLE)
38+
Every feature MUST be implemented as a reusable GitHub Actions workflow component. This is NOT a local development framework; it is designed for CI/CD execution. Workflows MUST:
39+
- Be composable and callable from other workflows using `uses:` syntax
40+
- Use clearly defined inputs and outputs with proper documentation
41+
- Follow the single responsibility principle (one workflow = one concern)
42+
- Support matrix strategies for parallel execution where appropriate
43+
- Be independently testable via the CI validation workflow (`.github/workflows/ci.yml`)
44+
- Delegate logic to reusable GitHub Actions (from github.com/PSModule organization)
45+
- **Avoid inline PowerShell code** in workflow YAML; use action-based script files instead
46+
- Reference actions by specific versions or tags for stability
47+
48+
**Rationale**: Reusable workflow architecture enables maintainability, reduces duplication, and allows consuming repositories to leverage Process-PSModule capabilities consistently. Action-based scripts provide better testability, reusability, and version control than inline code.
49+
50+
### II. Test-Driven Development (NON-NEGOTIABLE)
51+
All code changes MUST follow strict TDD practices using Pester and PSScriptAnalyzer:
52+
- Tests MUST be written before implementation
53+
- Tests MUST fail initially (Red phase)
54+
- Implementation proceeds only after failing tests exist (Green phase)
55+
- Code MUST be refactored while maintaining passing tests (Refactor phase)
56+
- PSScriptAnalyzer rules MUST pass for all PowerShell code
57+
- Manual testing procedures MUST be documented when automated testing is insufficient
58+
- **Workflow functionality MUST be validated** through CI workflow tests (`.github/workflows/ci.yml`)
59+
- Consuming module repositories SHOULD use CI workflow for nightly validation
60+
61+
**Rationale**: TDD ensures code quality, prevents regressions, and creates living documentation through tests. This is fundamental to project reliability. CI workflow validation ensures the entire framework functions correctly in real-world scenarios.
62+
63+
### III. Platform Independence with Modern PowerShell
64+
All workflows and features MUST support cross-platform execution (Linux, macOS, Windows) using **PowerShell 7.4 or newer**:
65+
- Use platform-agnostic PowerShell Core 7.4+ constructs exclusively
66+
- Implement matrix testing across all supported operating systems
67+
- Document any platform-specific behaviors or limitations
68+
- Test failures on any platform MUST block merging
69+
- Provide skip mechanisms for platform-specific tests when justified
70+
- **No backward compatibility** required for Windows PowerShell 5.1 or earlier PowerShell Core versions
1071

11-
### [PRINCIPLE_2_NAME]
12-
<!-- Example: II. CLI Interface -->
13-
[PRINCIPLE_2_DESCRIPTION]
14-
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
72+
**Rationale**: PowerShell 7.4+ provides consistent cross-platform behavior and modern language features. Focusing on a single modern version reduces complexity and maintenance burden while ensuring maximum compatibility for consuming projects on contemporary platforms.
1573

16-
### [PRINCIPLE_3_NAME]
17-
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
18-
[PRINCIPLE_3_DESCRIPTION]
19-
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
74+
### IV. Quality Gates and Observability
75+
Every workflow execution MUST produce verifiable quality metrics:
76+
- Test results MUST be captured in structured formats (JSON reports)
77+
- Code coverage MUST be measured and reported
78+
- Linting results MUST be captured and enforced
79+
- All quality gates MUST fail the workflow if thresholds are not met
80+
- Workflow steps MUST produce clear, actionable error messages
81+
- Debug mode MUST be available for troubleshooting
2082

21-
### [PRINCIPLE_4_NAME]
22-
<!-- Example: IV. Integration Testing -->
23-
[PRINCIPLE_4_DESCRIPTION]
24-
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
83+
**Rationale**: Measurable quality gates prevent degradation over time and provide clear feedback. Observability enables rapid debugging and continuous improvement.
2584

26-
### [PRINCIPLE_5_NAME]
27-
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
28-
[PRINCIPLE_5_DESCRIPTION]
29-
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
85+
### V. Continuous Delivery with Semantic Versioning
86+
Release management MUST be automated and follow SemVer 2.0.0:
87+
- Version bumps MUST be determined by PR labels (major, minor, patch)
88+
- Releases MUST be automated on merge to main branch
89+
- PowerShell Gallery publishing MUST be automatic for labeled releases
90+
- GitHub releases MUST be created with complete changelogs
91+
- Prerelease versioning MUST support incremental or date-based formats
92+
- Documentation MUST be published to GitHub Pages automatically
3093

31-
## [SECTION_2_NAME]
32-
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
94+
**Rationale**: Automated releases reduce human error, ensure consistency, and enable rapid iteration while maintaining clear version semantics.
3395

34-
[SECTION_2_CONTENT]
35-
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
96+
## Quality Standards
3697

37-
## [SECTION_3_NAME]
38-
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
98+
### Technical Constraints
99+
- **PowerShell Version**: 7.4 or newer (no backward compatibility with 5.1 or older Core versions)
100+
- **Execution Environment**: GitHub Actions runners (not designed for local development)
101+
- **Code Organization**: Action-based scripts preferred over inline workflow code
102+
- **Action References**: Use PSModule organization actions (github.com/PSModule) with version tags
103+
- **Workflow Structure**: Reusable workflows in `.github/workflows/` using `workflow_call` trigger
39104

40-
[SECTION_3_CONTENT]
41-
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
105+
### Code Quality
106+
- All PowerShell code MUST pass PSScriptAnalyzer with project-defined rules
107+
- Source code structure MUST follow PSModule framework conventions
108+
- Code coverage target MUST be configurable per repository (default 0% for flexibility)
109+
- All workflow YAML MUST be valid and pass linting
110+
- Action scripts MUST be testable and maintainable
111+
- Inline code in workflows SHOULD be avoided; extract to action scripts
112+
113+
### Documentation
114+
- README MUST provide clear setup instructions and workflow usage examples
115+
- All workflows MUST include descriptive comments explaining inputs, outputs, and purpose
116+
- Changes MUST update relevant documentation in the same PR
117+
- GitHub Pages documentation MUST be generated automatically using Material for MkDocs
118+
119+
### Testing
120+
- Source code tests MUST validate framework compliance
121+
- Module tests MUST validate built module integrity
122+
- Local module tests (Pester) MUST validate functional behavior
123+
- BeforeAll/AfterAll setup and teardown scripts MUST be supported for test environments
124+
- Test matrices MUST be configurable via repository settings
125+
- **CI validation workflow** (`.github/workflows/ci.yml`) MUST be maintained for integration testing
126+
- **Production workflow** (`.github/workflows/workflow.yml`) is the primary consumer-facing workflow
127+
- Consuming repositories SHOULD use CI workflow for nightly regression testing
128+
129+
## Development Workflow
130+
131+
### Branching and Pull Requests
132+
- Follow GitHub Flow: feature branches → PR → main
133+
- PR MUST be opened for all changes
134+
- CI workflows MUST execute on PR synchronize, open, reopen, label events
135+
- PR labels determine release behavior (major, minor, patch, NoRelease)
136+
137+
### Workflow Execution Order
138+
The standard execution order for Process-PSModule workflows MUST be:
139+
1. **Get-Settings** - Reads configuration and prepares test matrices
140+
2. **Build-Module** - Compiles source into module
141+
3. **Test-SourceCode** - Parallel matrix testing of source code standards
142+
4. **Lint-SourceCode** - Parallel matrix linting of source code
143+
5. **Test-Module** - Framework validation and linting of built module
144+
6. **Test-ModuleLocal** - Runs Pester tests with BeforeAll/AfterAll support
145+
7. **Get-TestResults** - Aggregates and validates test results
146+
8. **Get-CodeCoverage** - Validates coverage thresholds
147+
9. **Build-Docs** and **Build-Site** - Generates documentation
148+
10. **Publish-Module** and **Publish-Site** - Automated publishing on release
149+
150+
**Workflow Types**:
151+
- **Production Workflow** (`.github/workflows/workflow.yml`) - Main workflow for consuming repositories
152+
- **CI Validation Workflow** (`.github/workflows/ci.yml`) - Integration tests for framework development
153+
- Consuming repositories use production workflow for releases, CI workflow for nightly validation
154+
155+
### Configuration
156+
- Settings MUST be stored in `.github/PSModule.yml` (or JSON/PSD1 format)
157+
- Skip flags MUST be available for all major workflow steps
158+
- OS-specific skip flags MUST be supported (Linux, macOS, Windows)
159+
- Settings MUST support test configuration, build options, and publish behavior
42160

43161
## Governance
44-
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
45162

46-
[GOVERNANCE_RULES]
47-
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
163+
### Constitution Authority
164+
This constitution supersedes all other development practices. When conflicts arise between this document and other guidance, the constitution takes precedence.
165+
166+
### Amendments
167+
Changes to this constitution require:
168+
1. Documentation of the proposed change with clear rationale
169+
2. Review and approval by project maintainers
170+
3. Migration plan for existing code/workflows if applicable
171+
4. Version bump according to impact:
172+
- MAJOR: Backward incompatible principle removals or redefinitions
173+
- MINOR: New principles or materially expanded guidance
174+
- PATCH: Clarifications, wording fixes, non-semantic refinements
175+
176+
### Compliance
177+
- All PRs MUST be validated against constitutional principles
178+
- Workflow design MUST align with Workflow-First Design principle
179+
- Test-First principle compliance is NON-NEGOTIABLE and enforced by review
180+
- Platform Independence MUST be verified through matrix testing results
181+
- Quality Gates MUST be enforced by workflow automation
182+
- PowerShell 7.4+ compatibility MUST be verified
183+
- Action-based implementation preferred over inline workflow code
184+
- CI validation workflow MUST pass before merging changes to core workflows
185+
186+
### Runtime Development Guidance
187+
For agent-specific runtime development guidance, agents should reference:
188+
- GitHub Copilot: `.github/copilot-instructions.md` (if exists)
189+
- Other agents: Check for `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `QWEN.md`
48190

49-
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
50-
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
191+
**Version**: 1.1.0 | **Ratified**: TODO(RATIFICATION_DATE) | **Last Amended**: 2025-10-01

‎.specify/templates/plan-template.md‎

Lines changed: 51 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -34,20 +34,58 @@
3434
[Extract from feature spec: primary requirement + technical approach from research]
3535

3636
## 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]
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]
4141
**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]
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]
4545
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
4646

4747
## Constitution Check
4848
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
4949

50-
[Gates determined based on constitution file]
50+
### I. Workflow-First Design (NON-NEGOTIABLE)
51+
- [ ] Feature is implemented as reusable GitHub Actions workflow(s)
52+
- [ ] Workflows have clearly defined inputs and outputs
53+
- [ ] Workflows follow single responsibility principle
54+
- [ ] Matrix strategies used for parallel execution where appropriate
55+
- [ ] Workflows are independently testable via CI validation workflow
56+
- [ ] Logic delegated to reusable GitHub Actions (PSModule organization)
57+
- [ ] Inline PowerShell code avoided; action-based scripts used instead
58+
- [ ] Actions referenced by specific versions/tags
59+
60+
### II. Test-Driven Development (NON-NEGOTIABLE)
61+
- [ ] Tests will be written before implementation
62+
- [ ] Initial tests will fail (Red phase documented)
63+
- [ ] Implementation plan includes making tests pass (Green phase)
64+
- [ ] Refactoring phase planned while maintaining tests
65+
- [ ] PSScriptAnalyzer validation included
66+
- [ ] Manual testing documented if needed
67+
- [ ] CI validation workflow tests included
68+
69+
### III. Platform Independence with Modern PowerShell
70+
- [ ] PowerShell 7.4+ constructs used exclusively
71+
- [ ] Matrix testing across Linux, macOS, Windows included
72+
- [ ] Platform-specific behaviors documented
73+
- [ ] Skip mechanisms justified if platform-specific tests needed
74+
- [ ] No backward compatibility with PowerShell 5.1 required
75+
76+
### IV. Quality Gates and Observability
77+
- [ ] Test results captured in structured JSON format
78+
- [ ] Code coverage measurement included
79+
- [ ] Linting results captured and enforced
80+
- [ ] Quality gate thresholds defined
81+
- [ ] Clear error messages planned
82+
- [ ] Debug mode support included
83+
84+
### V. Continuous Delivery with Semantic Versioning
85+
- [ ] Version bump strategy documented (labels, SemVer)
86+
- [ ] Release automation compatible with existing workflow
87+
- [ ] Documentation updates included
88+
- [ ] GitHub Pages publishing considered if docs changes
5189

5290
## Project Structure
5391

@@ -169,12 +207,12 @@ directories captured above]
169207
- Load `.specify/templates/tasks-template.md` as base
170208
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
171209
- Each contract → contract test task [P]
172-
- Each entity → model creation task [P]
210+
- Each entity → model creation task [P]
173211
- Each user story → integration test task
174212
- Implementation tasks to make tests pass
175213

176214
**Ordering Strategy**:
177-
- TDD order: Tests before implementation
215+
- TDD order: Tests before implementation
178216
- Dependency order: Models before services before UI
179217
- Mark [P] for parallel execution (independent files)
180218

@@ -185,8 +223,8 @@ directories captured above]
185223
## Phase 3+: Future Implementation
186224
*These phases are beyond the scope of the /plan command*
187225

188-
**Phase 3**: Task execution (/tasks command creates tasks.md)
189-
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
226+
**Phase 3**: Task execution (/tasks command creates tasks.md)
227+
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
190228
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
191229

192230
## Complexity Tracking
@@ -216,4 +254,4 @@ directories captured above]
216254
- [ ] Complexity deviations documented
217255

218256
---
219-
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*
257+
*Based on Constitution v1.1.0 - See `.specify/memory/constitution.md`*

0 commit comments

Comments
 (0)