telo3-ai 5.0.7 → 6.2.0

package/templates/memory.md

@@ -1,368 +1,30 @@
-# Project Memory
+<!-- Rolling summary, NOT a conversation transcript. Read FIRST every session (memory resets
+     between sessions). Prune stale entries; keep only what the next session needs. -->
 
-> **Purpose:** Track CURRENT STATE — recent work, important decisions, continuity information, and project-specific knowledge.  
-> **Last Updated:** [Date]
-
----
+# Project Memory — [Project Name]
 
 ## Current State
 
-### Project Status
-**Overall status:** [Not Started / Active Development / MVP Complete / Production / Maintenance]
-
-**Current phase:** [e.g., Phase 2 — Core Features]
-
-**Active work:**
-- [What is currently being worked on]
-- [Current focus areas]
-
-**Last deployed:** [Date or N/A]
-
----
+[TODO: Where the project is right now — what works, what's in progress, the next step.]
 
 ## Recently Completed Work
 
-### [Date Range: e.g., Last 2 Weeks]
-
-- **[Date]:** [Completed work item]
-  - **Details:** [Brief description of what was done]
-  - **Impact:** [How this affects the product]
-  - **Files changed:** [Key files if relevant]
-
-- **[Date]:** [Completed work item]
-
----
+- [TODO: change — files touched — outcome (keep last ~5-10, prune older)]
 
 ## Important Decisions
 
-[Decisions that should not be reversed without careful consideration]
-
-### [Date]: [Decision Title]
-**Decision:** [What was decided]  
-**Rationale:** [Why this decision was made]  
-**Context:** [What was the situation that led to this decision]  
-**Alternatives considered:** [What else was considered]  
-**Trade-offs:** [What are the downsides]  
-**Status:** [Active / Under Review / Superseded]  
-**DO NOT reverse without:** [Criteria for reconsidering]
-
----
-
-## Architectural Decisions
-
-### Current Architecture Choices
-
-- **[Technology/Pattern choice]:** [Why chosen]
-  - **Reason:** [Detailed rationale]
-  - **Alternatives:** [What was not chosen and why]
-
----
-
-## Known Issues & Bugs
-
-### Critical
-- **[Issue description]**
-  - **Impact:** [How this affects users]
-  - **Workaround:** [Temporary solution if available]
-  - **Plan:** [How/when will this be fixed]
-
-### Non-Critical
-- **[Issue description]**
-  - **Impact:** 
-  - **Priority:** [When this might be addressed]
-
----
-
-## Known Limitations
-
-[Documented limitations of the current implementation]
-
-- **[Limitation 1]:** [Description]
-  - **Reason:** [Why this limitation exists]
-  - **Future plan:** [If/when this might be addressed]
-
-- **[Limitation 2]:** [Description]
-
----
-
-## Technical Debt
-
-[Technical debt that has been explicitly accepted, with context]
-
-- **[Debt item]:**
-  - **Introduced:** [When and why was this shortcut taken]
-  - **Impact:** [What is the cost of this debt]
-  - **Plan:** [When/how should this be addressed]
-
----
-
-## Temporary Workarounds
-
-[Temporary solutions that should be revisited]
-
-- **[Workaround description]:**
-  - **Location:** [Where in code]
-  - **Reason:** [Why was this necessary]
-  - **Replace with:** [What is the proper solution]
-  - **Timeline:** [When should this be addressed]
-
----
+| Decision | Why | Date |
+|----------|-----|------|
+| [TODO] | [TODO] | [TODO] |
 
-## Important Discoveries
+## Known Issues
 
-[Findings, insights, or lessons learned during development]
-
-### Technical Discoveries
-- **[Discovery]:** [What was learned]
-  - **Implication:** [How this affects the project]
-
-### User Insights
-- **[Insight]:** [What was learned about users]
-  - **Action:** [How this influences design/development]
-
----
-
-## Security Considerations
-
-[Security-related information that must remain known]
-
-### Implemented Security Controls
-- [Control 1: e.g., "Rate limiting on auth endpoints"]
-- [Control 2]
-
-### Security Decisions
-- **[Decision]:** [e.g., "Using bcrypt for password hashing"]
-  - **Reason:** [Why this approach]
-
-### Security TODOs
-- [ ] [Security improvement needed]
-
-**IMPORTANT:** Never store secrets, API keys, or credentials in this document.
-
----
-
-## Privacy Considerations
-
-[Privacy-sensitive functionality and decisions]
-
-### Data Collection
-- **Personal data collected:** [Types of data]
-- **Purpose:** [Why each type is collected]
-- **Retention:** [How long data is kept]
-
-### Third-Party Services
-- **[Service name]:** [What data is shared]
-  - **Purpose:** [Why this service is used]
-  - **Privacy policy:** [Link]
-
-### Privacy Decisions
-- **[Decision]:** [e.g., "Self-hosting fonts instead of Google Fonts"]
-  - **Reason:** [Why this was chosen]
-
----
-
-## Legal & Compliance Considerations
-
-> **Note:** This section documents engineering decisions related to legal/compliance considerations, not legal advice.
-
-### Applicable Considerations
-- **[Area: e.g., "Age restrictions"]:** [Status and implementation]
-- **[Area: e.g., "Email unsubscribe"]:** [Status and implementation]
-
-### Compliance TODOs
-- [ ] [Compliance-related task]
-
-**IMPORTANT:** Verify current legal requirements with qualified counsel before claiming compliance.
-
----
+- [TODO: bug/limitation — impact — workaround if any]
 
 ## Pending Questions
 
-[Open questions that need to be resolved]
-
-- [ ] **[Question]:** [What needs to be clarified]
-  - **Impact:** [Why this matters]
-  - **Owner:** [Who should answer this]
-
----
-
-## Recent Architectural Changes
-
-[Significant changes to architecture or patterns]
-
-### [Date]: [Change description]
-**What changed:** [Description]  
-**Why:** [Rationale]  
-**Migration status:** [Complete / In Progress / Not Started]  
-**Follow-up needed:** [Any remaining work]
-
----
-
-## Project-Specific Preferences
-
-[Preferences established for this project that differ from defaults or are important to remember]
-
-### Code Preferences
-- **[Preference]:** [e.g., "Prefer server components over client components in Next.js"]
-  - **Reason:** [Why this preference exists]
-
-### Design Preferences
-- **[Preference]:** [e.g., "Avoid shadows on buttons"]
-  - **Reason:** [Why this is preferred]
-
-### Process Preferences
-- **[Preference]:** [e.g., "Always include tests with new features"]
-  - **Reason:** [Why this is important]
-
----
-
-## Stakeholder Context
-
-[Important context about stakeholders, if applicable]
-
-- **Primary stakeholder:** [Name/Role]
-  - **Priorities:** [What matters most to them]
-  - **Communication preference:** [How they prefer updates]
-
----
-
-## Environment-Specific Notes
-
-### Development
-- [Important information about dev environment]
-
-### Staging
-- [Important information about staging environment]
-
-### Production
-- [Important information about production environment]
-
----
-
-## Integration-Specific Notes
-
-[Notes about external service integrations]
-
-### [Service Name]
-- **Account:** [Account information (not credentials)]
-- **Configuration:** [Important configuration details]
-- **Gotchas:** [Things to watch out for]
-- **Docs:** [Link to service documentation]
-
----
-
-## Performance Notes
-
-[Performance-related observations and decisions]
-
-- **[Observation]:** [Performance finding]
-  - **Impact:** [Effect on user experience]
-  - **Action taken:** [What was done about it]
-
----
-
-## Onboarding Notes
-
-[Information helpful for new developers joining the project]
-
-### Getting Started
-- [Key information for new team members]
-
-### Common Pitfalls
-- **[Pitfall]:** [Common mistake]
-  - **Solution:** [How to avoid it]
-
-### Useful Commands
-```bash
-# [Command description]
-npm run [command]
-```
-
----
-
-## Team Agreements
-
-[Agreements the team has made about how to work]
-
-- **[Agreement]:** [e.g., "Always update tasks.md after completing work"]
-- **[Agreement]:** [e.g., "Run tests before opening PR"]
-
----
-
-## Deferred Decisions
-
-[Decisions that have been explicitly deferred]
-
-- **[Decision topic]:**
-  - **Why deferred:** [Reason for waiting]
-  - **Revisit when:** [Criteria or timeline]
-
----
-
-## Migration Notes
-
-[If migrating from another system or undergoing significant changes]
-
-### Migration Status
-- **From:** [Old system]
-- **To:** [New system]
-- **Progress:** [X% complete or status]
-- **Remaining work:** [What's left]
-
----
-
-## Monitoring & Observability
-
-[Important information about monitoring and debugging]
-
-### Key Metrics
-- **[Metric]:** [Where to find it, what it means]
-
-### Debugging Tips
-- **[Tip]:** [Useful debugging information]
-
----
-
-## Seasonal / Time-Based Notes
-
-[Information that applies at specific times]
-
-- **[Period]:** [Special considerations]
-
----
-
-## Important Don'ts
-
-[Explicit prohibitions or things to avoid based on past experience]
-
-- ❌ **[Don't do this]:** [Why not]
-- ❌ **[Don't do this]:** [Why not]
-
----
-
-## Context for AI Agents
-
-[Specific guidance for AI coding assistants working on this project]
-
-### Preferred Patterns
-- [Pattern AI should follow]
-
-### Avoid
-- [Pattern AI should avoid]
-
-### Always Check
-- [Files AI should always reference before making changes]
-
----
-
-## Notes
-
-[Miscellaneous important information that doesn't fit elsewhere]
-
----
+- [UNKNOWN: open question for the user — don't invent the answer.]
 
-## Document History
+## Context For The Next Session
 
-| Date | Author | Changes |
-|------|--------|---------|
-| [Date] | [Name] | Initial version |
+[TODO: The one thing the next session must not forget. Keep this short and current.]

package/templates/prd.md

@@ -1,320 +1,40 @@
-# Product Requirements Document (PRD)
+<!-- Lean skeleton. Fill each section with real content; delete what doesn't apply.
+     Required sections are validated by `telo3 validate`. Keep it focused, not a questionnaire. -->
 
-> **Purpose:** Define WHAT the product is and WHY it exists.  
-> **Last Updated:** [Date]
-
----
+# Product Requirements — [Project Name]
 
 ## Project Overview
 
-### Project Name
-[Product name]
-
-### Product Summary
-[2-3 sentence description of what this product is and what it does]
-
-### Vision
-[What is the long-term vision? What change do you want to create? What problem are you solving at scale?]
-
----
+[TODO: One paragraph — what this product is and the value it delivers.]
 
 ## Problem Statement
 
-### The Problem
-[Describe the problem that exists today. Who experiences it? How does it affect them?]
-
-### Current Alternatives
-[What do people use today? Why are current solutions insufficient?]
-
-### Opportunity
-[Why is now the right time to solve this problem? What has changed?]
-
----
+[TODO: The specific problem, who has it, and why current solutions fail.]
 
 ## Target Users
 
-### Primary Users
-[Who is this product for? Be specific about demographics, roles, needs, behaviors.]
-
-### User Segments
-| Segment | Description | Key Needs | Priority |
-|---------|-------------|-----------|----------|
-| [Segment name] | [Who they are] | [What they need] | High/Medium/Low |
-
-### User Personas (Optional)
-[If helpful, describe 1-2 representative personas with goals, pain points, and context]
-
----
-
-## Core Use Cases
-
-### Primary Use Cases
-1. **[Use case name]**
-   - **User goal:** [What is the user trying to accomplish?]
-   - **Current flow:** [How do they do it today?]
-   - **Proposed flow:** [How will they do it with this product?]
-   - **Value:** [What improvement does this provide?]
-
-2. **[Use case name]**
-   - **User goal:** 
-   - **Current flow:** 
-   - **Proposed flow:** 
-   - **Value:** 
-
-### Secondary Use Cases
-[Less critical use cases that are supported but not central to the product]
-
----
+[TODO: Primary users/roles. Note audience constraints (e.g. children, enterprise, region).]
 
 ## Goals
 
-### Business Goals
-- [What business outcomes are we trying to achieve?]
-- [How will we measure success from a business perspective?]
-
-### User Goals
-- [What outcomes are we trying to create for users?]
-- [How will we measure user success?]
-
-### Technical Goals
-- [Any technical objectives? Performance targets? Scalability goals?]
-
----
+- [TODO: Measurable goal 1]
+- [TODO: Measurable goal 2]
 
 ## Non-Goals
 
-[What is explicitly OUT of scope? What will we NOT do? This prevents scope creep and clarifies boundaries.]
-
-- [Non-goal 1]
-- [Non-goal 2]
-
----
+- [TODO: Explicitly out of scope — prevents scope creep.]
 
 ## Functional Requirements
 
-### Core Features (MVP)
-
-#### [Feature 1 Name]
-- **Description:** [What does this feature do?]
-- **User value:** [Why is this important?]
-- **Acceptance criteria:**
-  - [ ] [Specific, testable criterion]
-  - [ ] [Specific, testable criterion]
-- **Priority:** Must-have / Should-have / Nice-to-have
-
-#### [Feature 2 Name]
-- **Description:** 
-- **User value:** 
-- **Acceptance criteria:**
-  - [ ] 
-- **Priority:** 
-
-### Future Features
-
-[Features that are important but not part of MVP. Include rough priority and rationale.]
-
-- **[Feature name]:** [Description] — Priority: [High/Medium/Low]
-
----
-
-## User Experience Requirements
-
-### Key User Flows
-[Describe critical user journeys from entry to goal completion]
-
-1. **[Flow name]:** [Entry point] → [Steps] → [Outcome]
-
-### Accessibility Requirements
-- [ ] WCAG 2.1 Level AA compliance
-- [ ] Keyboard navigation support
-- [ ] Screen reader compatibility
-- [ ] [Other specific requirements]
-
-### Responsive Behavior
-- [ ] Mobile-first design
-- [ ] Tablet optimization
-- [ ] Desktop experience
-- [ ] [Specific breakpoint requirements]
-
-### Performance Requirements
-- [ ] Page load < [X] seconds
-- [ ] Time to interactive < [X] seconds
-- [ ] [Other specific performance targets]
-
----
-
-## Technical Requirements
-
-### Platform
-- [ ] Web application
-- [ ] Mobile (iOS/Android)
-- [ ] Desktop
-- [ ] API/Backend service
-- [ ] [Other]
-
-### Browser/Device Support
-- **Browsers:** [Specify minimum versions]
-- **Devices:** [Specify device support requirements]
-
-### Data Requirements
-- **Data sources:** [Where does data come from?]
-- **Data storage:** [What needs to be persisted?]
-- **Data retention:** [How long is data kept?]
-- **Data privacy:** [What are privacy requirements?]
-
-### Integration Requirements
-[External services, APIs, or systems that must be integrated]
-
-- **[Service name]:** [Purpose] — [Criticality]
-
----
-
-## Security & Privacy Requirements
-
-### Authentication
-- [ ] User registration/login required
-- [ ] Social authentication (Google, GitHub, etc.)
-- [ ] SSO (enterprise)
-- [ ] [Other]
-
-### Authorization
-- [ ] Role-based access control
-- [ ] Permission levels: [Specify]
-- [ ] [Other]
-
-### Privacy
-- [ ] Personal data collected: [List types]
-- [ ] Third-party data sharing: [List services]
-- [ ] User consent required for: [List]
-- [ ] Data deletion supported: [Yes/No]
-- [ ] Cookie usage: [Essential/Analytics/Marketing]
-
-### Compliance Considerations
-[Mark as applicable and note jurisdiction when relevant]
-
-- [ ] Children's privacy (e.g., COPPA for U.S.) — [Details]
-- [ ] Marketing email (e.g., CAN-SPAM, GDPR) — [Details]
-- [ ] Subscriptions/auto-renewal — [Details]
-- [ ] User-generated content / DMCA — [Details]
-- [ ] [Other applicable regulations] — [Details]
-
-> **Note:** This is a decision-support tool. Verify applicable legal requirements with qualified counsel before claiming compliance.
-
----
-
-## Constraints
-
-### Technical Constraints
-[Limitations imposed by existing systems, technology choices, or infrastructure]
-
-- [Constraint 1]
-
-### Business Constraints
-[Budget, timeline, resource, or strategic limitations]
-
-- [Constraint 1]
-
-### Regulatory Constraints
-[Legal or compliance requirements that limit design or implementation]
-
-- [Constraint 1]
-
----
-
-## Dependencies
-
-### Internal Dependencies
-[Other projects, teams, or systems this project depends on]
-
-- **[Dependency name]:** [Description] — [Status]
-
-### External Dependencies
-[Third-party services, vendors, or external factors]
-
-- **[Dependency name]:** [Description] — [Risk level]
-
----
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-1 | [TODO: what the system must do] | must |
+| FR-2 | [TODO] | should |
 
 ## Success Criteria
 
-### Launch Criteria
-[What must be true before this product can launch?]
-
-- [ ] [Criterion 1]
-- [ ] [Criterion 2]
-
-### Success Metrics
-[How will we measure whether this product is successful?]
-
-| Metric | Target | Timeframe | Measurement Method |
-|--------|--------|-----------|-------------------|
-| [Metric name] | [Target value] | [When] | [How measured] |
-
----
-
-## Timeline & Milestones
-
-### MVP Milestones
-| Milestone | Target Date | Status |
-|-----------|-------------|--------|
-| [Milestone 1] | [Date] | Not Started / In Progress / Complete |
-
-### Future Phases
-[Post-MVP roadmap at a high level]
-
-- **Phase 2:** [Description] — Target: [Timeframe]
-- **Phase 3:** [Description] — Target: [Timeframe]
-
----
-
-## Product Decisions
-
-[Document important product decisions here. Include the decision, rationale, date, and who decided.]
-
-### [Decision Date]: [Decision Title]
-**Decision:** [What was decided?]  
-**Rationale:** [Why was this decided?]  
-**Alternatives considered:** [What else was considered?]  
-**Trade-offs:** [What are the downsides of this choice?]
-
----
-
-## Current Product Status
-
-**Current State:** [Not Started / In Development / MVP Complete / Active / Maintenance]
-
-**Implemented Features:**
-- [Feature 1] — [Status]
-- [Feature 2] — [Status]
-
-**Known Limitations:**
-- [Limitation 1]
-
-**Pending Decisions:**
-- [Open question 1]
-
----
+[TODO: How we know it works — metrics, acceptance checks.]
 
 ## Open Questions
 
-[Questions that need to be answered before implementation or launch]
-
-- [ ] [Question 1]
-- [ ] [Question 2]
-
----
-
-## References
-
-- [Link to user research]
-- [Link to competitive analysis]
-- [Link to design mockups]
-- [Link to technical proposals]
-
----
-
-## Document History
-
-| Date | Author | Changes |
-|------|--------|---------|
-| [Date] | [Name] | Initial version |
+- [UNKNOWN: anything not yet decided — ask, don't invent.]