@intoinside/praxis 1.0.1

package/templates/intent-template.md

@@ -0,0 +1,290 @@
+# Feature Specification: [FEATURE NAME]
+
+**Template Version**: 2.0
+**Feature Branch**: `[###-feature-name]`
+**Created**: [DATE]
+**Status**: Draft
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language. Focus on what the user wants to achieve, not how the system will implement
+it. Keep it concise yet comprehensive.]
+
+**Why this priority**: [Explain the value and why it has this priority level. Consider business impact, user pain points,
+technical dependencies, and regulatory requirements.]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action]
+and delivers [specific value]. This test should verify that the user story provides standalone value without requiring
+other stories."]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+3. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language. Focus on what the user wants to achieve, not how the system will implement
+it. Keep it concise yet comprehensive.]
+
+**Why this priority**: [Explain the value and why it has this priority level. Consider business impact, user pain points,
+technical dependencies, and regulatory requirements.]
+
+**Independent Test**: [Describe how this can be tested independently. This test should verify that the user story provides
+standalone value without requiring other stories.]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language. Focus on what the user wants to achieve, not how the system will
+implement it. Keep it concise yet comprehensive.]
+
+**Why this priority**: [Explain the value and why it has this priority level. Consider business impact,
+user pain points, technical dependencies, and regulatory requirements.]
+
+**Independent Test**: [Describe how this can be tested independently. This test should verify that the user story
+provides standalone value without requiring other stories.]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases & Error Scenarios
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases and error conditions.
+-->
+
+- What happens when [boundary condition]? How should the system respond to [unusual input or load condition]?
+- How does the system handle [error scenario]? What is the user experience when [failure occurs]?
+- What are the boundary limits for [key data field or operation]?
+- How does the system behave when [external dependency] is unavailable?
+- What happens if [user action] is performed multiple times or at unexpected times?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+  Requirements must be:
+  - Specific and unambiguous
+  - Testable with clear acceptance criteria
+  - Aligned with user stories
+  - Prioritized by importance
+-->
+
+### Functional Requirements
+
+- **FR-001**: [Priority: P1] System MUST [specific capability, e.g., "allow users to create accounts"].
+  - Acceptance: [Clear testable conditions for this requirement]
+  - Dependencies: [Any other requirements this depends on]
+- **FR-002**: [Priority: P1] System MUST [specific capability, e.g., "validate email addresses"].
+  - Acceptance: [Clear testable conditions for this requirement]
+  - Dependencies: [Any other requirements this depends on]
+- **FR-003**: [Priority: P2] Users MUST be able to [key interaction, e.g., "reset their password"].
+  - Acceptance: [Clear testable conditions for this requirement]
+  - Dependencies: [Any other requirements this depends on]
+- **FR-004**: [Priority: P2] System MUST [data requirement, e.g., "persist user preferences"].
+  - Acceptance: [Clear testable conditions for this requirement]
+  - Dependencies: [Any other requirements this depends on]
+- **FR-005**: [Priority: P3] System MUST [behavior, e.g., "log all security events"].
+  - Acceptance: [Clear testable conditions for this requirement]
+  - Dependencies: [Any other requirements this depends on]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Non-Functional Requirements
+
+- **NFR-001**: Performance - [System must meet performance criteria, e.g., "Handle 1000 concurrent users with
+<100ms response time"]
+- **NFR-002**: Security - [Security requirements, e.g., "Implement role-based access control"]
+- **NFR-003**: Scalability - [Scalability requirements, e.g., "Support 10x growth in user base"]
+- **NFR-004**: Usability - [Usability requirements, e.g., "Complete primary task in <5 clicks"]
+- **NFR-005**: Compliance - [Compliance requirements, e.g., "Meet GDPR requirements for data protection"]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation].
+  - Key attributes: [List essential fields without specifying storage or format]
+  - Relationships: [Connections to other entities]
+  - Validation rules: [Constraints and validation requirements]
+- **[Entity 2]**: [What it represents, relationships to other entities].
+  - Key attributes: [List essential fields without specifying storage or format]
+  - Relationships: [Connections to other entities]
+  - Validation rules: [Constraints and validation requirements]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+  Focus on outcomes for users and business, not implementation details.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes" - Focus on user experience]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation" - Focus on system performance]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt" -
+Focus on usability]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%" - Focus on business value]
+
+### Validation Approach
+
+**How we will measure success:**
+
+- [Specific metrics we will track]
+- [Tools/methods for collecting data]
+- [Timeline for measuring success]
+- [Who is responsible for validation]
+
+### Success Thresholds
+
+- **Minimum Viable**: [Baseline success criteria - what constitutes basic success]
+- **Target**: [Desired success criteria - what we're aiming for]
+- **Stretch Goal**: [Ambitious success criteria - what would exceed expectations]
+
+## Validation Checklist
+
+**Before proceeding to planning phase, verify:**
+
+- [ ] All user stories have acceptance criteria with Given/When/Then format
+- [ ] Success criteria are measurable with specific metrics
+- [ ] Edge cases adequately cover error conditions and boundary values
+- [ ] All [NEEDS CLARIFICATION] markers are resolved
+- [ ] Requirements are testable and unambiguous
+- [ ] Security considerations are addressed if applicable
+- [ ] Performance requirements are specified if applicable
+- [ ] Dependencies and assumptions are documented
+
+## Quality Scoring
+
+**Rate each section from 1-5 (5 = Excellent):**
+
+### User Stories Quality (Score: ___/5)
+
+- [ ] Clear user value proposition
+- [ ] Appropriate level of detail
+- [ ] Measurable acceptance criteria
+- [ ] Proper prioritization (P1/P2/P3)
+- [ ] Independent testability
+
+### Requirements Quality (Score: ___/5)
+
+- [ ] All requirements are testable
+- [ ] Technology-agnostic language
+- [ ] Clear acceptance criteria
+- [ ] Non-functional requirements included
+- [ ] Aligned with user stories
+
+### Success Criteria Quality (Score: ___/5)
+
+- [ ] All criteria are measurable
+- [ ] Specific metrics defined
+- [ ] Technology-agnostic
+- [ ] Include success thresholds (minimum/target/stretch)
+- [ ] Cover user, business, and technical outcomes
+
+### Overall Quality (Score: ___/5)
+
+**Recommendation**: [Proceed to planning / Needs revision / Needs major revision]
+
+## Automated Testing Guidance
+
+### Test Strategy Alignment
+
+Based on your feature specification, consider implementing these test types:
+
+- **Unit Tests**: For individual functions, methods, and classes
+- **Integration Tests**: For component interactions and API endpoints
+- **Contract Tests**: For API compatibility between services
+- **End-to-End Tests**: For critical user journeys
+- **Performance Tests**: If performance requirements specified
+- **Security Tests**: If security requirements specified
+
+### Test Documentation
+
+- Document test scenarios in `tests/scenarios/[feature-name].md`
+- Create test data in `tests/fixtures/[feature-name]/`
+- Define test environments in `tests/config/[environment].json`
+- Include load testing scripts if performance is critical
+
+## Risk Assessment Template
+
+### Technical Risks
+
+| Risk | Impact (H/M/L) | Probability (H/M/L) | Mitigation Strategy | Owner |
+|------|----------------|-------------------|-------------------|-------|
+| [e.g., Third-party API dependency] | [High] | [Medium] | [Have fallback option] | [Dev Team] |
+| | | | | |
+| | | | | |
+
+### Security Risks
+
+- **Data exposure**: [Mitigation strategy]
+- **Authentication/authorization**: [Mitigation strategy]
+- **Input validation**: [Mitigation strategy]
+- **Compliance**: [Mitigation strategy]
+
+### Performance Risks
+
+- **Scalability**: [Expected load vs. capacity]
+- **Response time**: [Required vs. projected times]
+- **Resource usage**: [CPU, memory, storage projections]
+
+### Project Risks
+
+- **Timeline**: [Critical path dependencies]
+- **Resources**: [Required skills/availability]
+- **Scope creep**: [Change management process]
+
+## Cross-Reference Validation
+
+### Forward Compatibility for plan.md
+
+- [ ] User stories have sufficient detail for technical planning
+- [ ] Requirements are specific enough for architecture decisions
+- [ ] Success criteria are measurable for implementation validation
+- [ ] Edge cases are detailed enough for comprehensive testing
+- [ ] Non-functional requirements provide clear technical direction
+
+### Consistency Check
+
+- [ ] All entities mentioned in user stories are captured in key entities section
+- [ ] Priorities assigned to user stories align with business value
+- [ ] Dependencies between user stories are identified
+- [ ] Acceptance criteria are specific enough to validate implementation
+- [ ] Security considerations are highlighted for planning phase

package/templates/spec-template.md

@@ -0,0 +1,114 @@
+# Feature Specification: [FEATURE NAME]
+
+**Intent**: [intent-id]
+**Created**: [DATE]  
+**Status**: Draft  
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": false,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  }
+}