@magic-ingredients/tiny-brain-local 0.13.1 → 0.14.10

package/templates/adr/README.md

@@ -1,243 +0,0 @@
-# Architecture Decision Records (ADRs)
-
-This repository uses Architecture Decision Records (ADRs) to document significant architectural and technical decisions.
-
-## What is an ADR?
-
-An Architecture Decision Record captures important architectural decisions along with their context and consequences. ADRs help teams:
-- Understand why decisions were made
-- Onboard new team members quickly
-- Avoid revisiting settled decisions
-- Track the evolution of the system architecture
-
-## Directory Structure
-
-```
-docs/adr/
-├── README.md                 # This file
-├── adr-template.md          # Template for new ADRs
-├── 0001-record-architecture-decisions.md
-├── 0002-use-postgresql-for-data-storage.md
-└── 0003-implement-event-sourcing.md
-```
-
-## File Naming Convention
-
-ADR files follow this naming pattern:
-```
-NNNN-decision-title-in-kebab-case.md
-```
-
-Where:
-- `NNNN` is a 4-digit sequential number (e.g., 0001, 0002, 0123)
-- Title uses kebab-case (lowercase, hyphens between words)
-- Keep titles concise but descriptive
-
-Examples:
-- `0001-record-architecture-decisions.md`
-- `0042-adopt-microservices-architecture.md`
-- `0123-migrate-from-mysql-to-postgresql.md`
-
-## ADR Status Lifecycle
-
-ADRs go through the following statuses:
-
-1. **proposed** - Decision is under consideration
-2. **accepted** - Decision has been approved and is active
-3. **deprecated** - Decision is no longer recommended but may still be in use
-4. **superseded** - Decision has been replaced by a newer ADR
-
-When superseding an ADR:
-- Update the old ADR's status to "superseded"
-- Set the `superseded_by` field to the new ADR number
-- Set the new ADR's `supersedes` field to the old ADR number
-- Link between the two documents
-
-## ADR Structure
-
-Each ADR uses Markdown with YAML frontmatter and contains:
-
-### YAML Frontmatter (Metadata)
-```yaml
----
-adr_number: 1
-title: "Brief Decision Title"
-date: 2025-01-15
-status: accepted
-supersedes: null
-superseded_by: null
-tags: [infrastructure, database]
-decision_makers: [Alice, Bob]
----
-```
-
-### Content Sections
-
-1. **Status** - Current state of the decision
-2. **Context** - The issue, constraints, and background
-3. **Decision** - What was decided (clear and specific)
-4. **Consequences** - Positive, negative, and neutral outcomes
-5. **Alternatives Considered** - Options evaluated and why they were rejected
-6. **Validation** - How the decision was tested/validated
-7. **References** - Links to code, docs, discussions
-8. **Notes** - Additional information and future considerations
-
-## Creating a New ADR
-
-### Manual Process
-
-1. Copy `adr-template.md`
-2. Determine the next sequential number
-3. Name the file: `NNNN-your-decision-title.md`
-4. Fill out all sections
-5. Update YAML frontmatter
-6. Commit and open PR for review
-
-### Using Claude Code
-
-Claude Code is configured to automatically create ADRs when making significant technical decisions. Simply ask Claude Code to:
-
-```bash
-# Claude will automatically:
-# - Determine the next ADR number
-# - Fill out the template
-# - Save to docs/adr/
-# - Follow all conventions
-
-"Document this decision as an ADR"
-"Create an ADR for choosing React over Vue"
-```
-
-## Guidelines for Writing Good ADRs
-
-### Do:
-✅ Write in clear, concise language
-✅ Focus on the decision, not the implementation details
-✅ Explain the "why" behind the decision
-✅ Document alternatives considered
-✅ Include validation and testing results
-✅ Link to relevant resources and code
-✅ Keep it objective and factual
-
-### Don't:
-❌ Include implementation code (link to it instead)
-❌ Make it too long (aim for 1-3 pages)
-❌ Use jargon without explanation
-❌ Skip the consequences section
-❌ Forget to update status when circumstances change
-
-## When to Create an ADR
-
-Create an ADR for decisions that:
-- Affect the system's structure or architecture
-- Are difficult or expensive to reverse
-- Impact multiple teams or components
-- Involve significant trade-offs
-- Set precedents for future decisions
-- Are likely to be questioned later
-
-Examples:
-- Choosing a database technology
-- Selecting a framework or library
-- Deciding on deployment strategy
-- Establishing coding standards
-- Picking authentication approach
-- Choosing between microservices vs monolith
-
-## When NOT to Create an ADR
-
-Skip ADRs for:
-- Routine bug fixes
-- Minor refactoring
-- Temporary workarounds
-- Individual code styling choices
-- Decisions easily reversed
-- Obvious, uncontroversial choices
-
-## ADR Review Process
-
-1. **Draft** - Create ADR with status "proposed"
-2. **Discussion** - Share with team for feedback
-3. **Decision** - Team makes final call
-4. **Accept** - Update status to "accepted"
-5. **Implement** - Build based on the decision
-6. **Review** - Periodically review active ADRs
-
-## Tips for Claude Code Integration
-
-### Automatic ADR Creation
-
-Claude Code will create ADRs automatically when it detects significant decisions. To optimize this:
-
-**Be explicit when making architectural decisions:**
-```
-"Let's use PostgreSQL for this. Can you create an ADR documenting this decision?"
-"We're choosing Terraform over CloudFormation. Document this as ADR."
-```
-
-**Claude will:**
-1. Analyze the decision context from the conversation
-2. Identify alternatives discussed
-3. Extract pros/cons from the discussion
-4. Determine appropriate metadata (tags, etc.)
-5. Generate a complete ADR
-6. Save it with the correct naming convention
-
-**Review the generated ADR:**
-- Claude's ADRs are comprehensive but review them
-- Add any missing context or validation
-- Verify the consequences are accurate
-- Ensure references are complete
-
-### Claude Code Instructions
-
-When working with ADRs, Claude Code follows these rules:
-
-1. **Numbering**: Always check existing ADRs to get the next sequential number
-2. **Naming**: Use kebab-case for file names
-3. **Completeness**: Fill out all sections (no TODOs or placeholders)
-4. **Context**: Include relevant conversation history in the Context section
-5. **Alternatives**: Document all options discussed, not just the winner
-6. **Validation**: Include actual test results or metrics when available
-7. **References**: Link to actual code changes, PRs, or commits
-8. **Status**: New ADRs start as "proposed" unless explicitly accepted
-
-## Maintaining ADRs
-
-### Regular Review
-- Review ADRs quarterly
-- Mark outdated decisions as deprecated
-- Update superseded ADRs
-- Remove truly obsolete ADRs (rare)
-
-### Updating Existing ADRs
-- Small clarifications: Edit directly
-- Significant changes: Create new superseding ADR
-- Add notes section for minor updates
-- Keep historical context intact
-
-### Linking ADRs
-- Reference related ADRs in the content
-- Use the "Related ADRs" section
-- Update both directions when linking
-- Consider creating decision trees for complex relationships
-
-## Example ADR
-
-See `0001-record-architecture-decisions.md` for a meta-ADR that documents the decision to use ADRs.
-
-## Resources
-
-- [ADR GitHub Organization](https://adr.github.io/)
-- [Markdown Guide](https://www.markdownguide.org/)
-- [YAML Specification](https://yaml.org/spec/)
-- [Architectural Decision Records (Martin Fowler)](https://martinfowler.com/articles/scaling-architecture-conversationally.html)
-
-## Questions?
-
-If you have questions about ADRs or need help creating one, reach out to the architecture team or ask Claude Code for assistance.
-
----
-
-**Last Updated:** 2025-01-15
-**Maintained By:** Architecture Team

package/templates/adr/_template/0001-record-architecture-decisions.md

@@ -1,223 +0,0 @@
----
-adr_number: 1
-title: "Record Architecture Decisions"
-date: 2025-01-15
-status: accepted
-supersedes: null
-superseded_by: null
-tags: [documentation, process, governance]
-decision_makers: [Architecture Team]
----
-
-# ADR-0001: Record Architecture Decisions
-
-## Status
-
-**accepted** (Date: 2025-01-15)
-
-## Context
-
-As our system grows in complexity, we need a way to capture important architectural decisions along with their context and consequences. Currently, decisions are scattered across:
-- Slack conversations that are difficult to search
-- Meeting notes in various formats
-- Tribal knowledge in team members' heads
-- Code comments that lack context
-
-This creates several problems:
-- New team members struggle to understand why systems are designed the way they are
-- Decisions get revisited repeatedly because rationale is lost
-- Context behind trade-offs is not preserved
-- Impact of changing decisions is unclear
-
-### Background
-
-The Architecture Decision Record (ADR) approach, popularized by Michael Nygard in 2011, provides a lightweight way to document architectural decisions. ADRs are:
-- Short documents (1-2 pages)
-- Stored in version control with the code
-- Immutable once accepted (new decisions supersede old ones)
-- Focused on significant decisions that affect structure, non-functional properties, dependencies, interfaces, or construction techniques
-
-### Constraints
-
-- Must integrate with existing development workflow
-- Should not add significant overhead to decision-making process
-- Needs to be searchable and maintainable
-- Must work well with version control
-- Should be accessible to both technical and non-technical stakeholders
-
-## Decision
-
-We will use Architecture Decision Records (ADRs) to capture significant architectural decisions. Specifically:
-
-- **Format**: Markdown files with YAML frontmatter
-- **Location**: `docs/adr/` directory in the main repository
-- **Naming**: Sequential numbering with kebab-case titles (e.g., `0001-record-architecture-decisions.md`)
-- **Template**: Standardized template covering context, decision, consequences, and alternatives
-- **Lifecycle**: Proposed → Accepted → (Deprecated or Superseded)
-- **Automation**: Claude Code integration for automatic ADR generation
-
-### Implementation Details
-
-1. Create `docs/adr/` directory structure
-2. Establish ADR template and README documentation
-3. Configure Claude Code with ADR creation instructions
-4. Begin documenting all significant new decisions
-5. Gradually backfill critical historical decisions
-
-## Consequences
-
-### Positive Consequences
-
-- **Knowledge preservation**: Decisions and rationale are permanently recorded
-- **Onboarding efficiency**: New team members can quickly understand system evolution
-- **Decision quality**: Forcing documentation encourages thorough consideration of alternatives
-- **Searchability**: Text files in git are easily searchable
-- **Historical context**: Clear record of when and why decisions were made
-- **Reduced decision revisiting**: Clear documentation reduces redundant discussions
-- **AI-friendly**: Claude Code can automatically create and reference ADRs
-
-### Negative Consequences
-
-- **Initial overhead**: Creating first ADRs and establishing process takes time
-- **Discipline required**: Team must commit to writing ADRs for significant decisions
-- **Maintenance burden**: ADRs need periodic review and updates
-- **Process learning curve**: Team needs to learn when and how to write ADRs
-- **Risk of over-documentation**: May be tempted to document trivial decisions
-
-### Neutral Consequences
-
-- **Cultural shift**: Changes team behavior around decision-making
-- **Review process**: ADRs should be reviewed like code changes
-- **Template evolution**: Template and process will likely evolve over time
-- **Tooling needs**: May eventually want better tooling for ADR visualization
-
-## Alternatives Considered
-
-### Alternative 1: Wiki Documentation
-
-**Description:** Use Confluence or similar wiki to document architectural decisions
-
-**Pros:**
-- Rich formatting options
-- Easy to link between documents
-- Built-in search functionality
-- Familiar to most teams
-
-**Cons:**
-- Separate from code repository
-- Not version controlled with code changes
-- Can become outdated easily
-- Requires additional tool/license
-- Less structured format
-
-**Rejection Reason:** ADRs in git are closer to the code, version controlled together, and don't require additional tools. The structured format encourages better decision documentation.
-
----
-
-### Alternative 2: Code Comments Only
-
-**Description:** Document architectural decisions in code comments or README files
-
-**Pros:**
-- No separate documentation to maintain
-- Close to implementation
-- No new process needed
-- Developers already write comments
-
-**Cons:**
-- Lacks structure and searchability
-- Gets lost in code noise
-- Not suitable for cross-cutting decisions
-- Difficult to find historical context
-- No clear lifecycle management
-
-**Rejection Reason:** Code comments are good for implementation details but poor for capturing architectural rationale, alternatives considered, and consequences. A separate, structured approach is needed.
-
----
-
-### Alternative 3: Design Documents in Google Docs
-
-**Description:** Write detailed design documents for each major decision
-
-**Pros:**
-- Rich formatting and diagrams
-- Real-time collaboration
-- Comment threads for discussions
-- Familiar tool for most teams
-
-**Cons:**
-- Not version controlled with code
-- Becomes outdated quickly
-- Access control complexity
-- Not searchable from codebase
-- Too heavyweight for many decisions
-- Separate from development workflow
-
-**Rejection Reason:** While design docs are valuable for complex features, ADRs provide a lighter-weight, version-controlled approach for capturing decisions. They complement, rather than replace, design docs.
-
----
-
-## Validation
-
-### Tests Performed
-
-- Reviewed ADR examples from multiple successful open-source projects
-- Prototyped ADR structure with markdown + YAML frontmatter
-- Tested integration with Claude Code for automatic generation
-- Verified searchability in GitHub and local development
-
-### Metrics Collected
-
-- Time to create ADR from template: ~15-30 minutes for detailed decisions
-- Time for Claude Code to generate ADR: ~2-3 minutes
-- Markdown file size: Typically 2-5KB per ADR
-- Readability score: High (markdown renders well on GitHub)
-
-### Success Criteria
-
-- [x] Template is clear and comprehensive
-- [x] Process integrates with git workflow
-- [x] Documents are easily searchable
-- [x] Format is both human and AI-friendly
-- [x] Can be automatically generated by Claude Code
-- [x] Minimal overhead for decision-makers
-
-## References
-
-- [Original ADR article by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
-- [ADR GitHub Organization](https://adr.github.io/)
-- [Markdown Guide](https://www.markdownguide.org/)
-- [YAML Frontmatter Specification](https://jekyllrb.com/docs/front-matter/)
-- [GitHub's Markdown Rendering](https://docs.github.com/en/get-started/writing-on-github)
-
-## Notes
-
-### Future Considerations
-
-- May want to build visualization tools to show ADR relationships
-- Consider adding ADR linting to CI/CD pipeline
-- Could generate ADR index/table of contents automatically
-- Might want to track ADR metrics (count by status, age, etc.)
-
-### Open Questions
-
-- Should we require ADRs for all decisions or only significant ones? (Answer: Only significant)
-- How often should we review ADRs? (Recommendation: Quarterly)
-- Who approves ADRs? (Answer: Architecture team or tech leads)
-
-### Follow-up Items
-
-- [ ] Train team on ADR process (completed: 2025-01-15)
-- [ ] Document 5-10 historical architectural decisions
-- [ ] Add ADR checklist to project onboarding
-- [ ] Schedule quarterly ADR review sessions
-
----
-
-**Related ADRs:**
-
-This is the foundational ADR. Future ADRs will reference this one as the basis for the documentation practice.
-
----
-
-*This ADR serves as both documentation of our ADR process and a template/example for future ADRs.*

package/templates/adr/_template/ADR_CREATION_INSTRUCTIONS.md

@@ -1,234 +0,0 @@
-# ADR Creation Instructions for Claude Code
-
-## When to Create an ADR
-
-Create an ADR automatically when you make decisions about:
-- Architecture patterns (microservices, event-driven, etc.)
-- Technology selection (databases, frameworks, libraries)
-- Infrastructure choices (cloud providers, IaC tools, CI/CD)
-- Security approaches (authentication, authorization)
-- Testing strategies (unit, integration, e2e frameworks)
-- API design (REST vs GraphQL, versioning)
-- Data storage/modeling decisions
-- Deployment strategies
-- Development workflows
-
-## ADR Creation Process
-
-### Step 1: Determine ADR Number
-```bash
-# List existing ADRs and get the highest number
-ls docs/adr/*.md | grep -E '[0-9]{4}' | sort | tail -1
-# Increment by 1 for new ADR number
-```
-
-### Step 2: Gather Information from Context
-
-Extract from conversation:
-- **Decision**: What was decided
-- **Context**: Why we're making this decision
-- **Constraints**: Technical, time, budget, team limitations
-- **Alternatives**: All options discussed (including rejected ones)
-- **Pros/Cons**: Benefits and drawbacks of each option
-- **Validation**: Any tests, prototypes, or benchmarks mentioned
-- **References**: Code, docs, or external resources mentioned
-
-### Step 3: Fill Out Template
-
-Use `docs/adr/adr-template.md` and populate:
-
-**YAML Frontmatter:**
-```yaml
-adr_number: [next sequential number]
-title: "[concise, descriptive title]"
-date: [YYYY-MM-DD - today's date]
-status: proposed  # or accepted if explicitly approved
-supersedes: null  # only if replacing an old ADR
-superseded_by: null
-tags: [relevant, technology, tags]
-decision_makers: [names if mentioned in conversation]
-```
-
-**Content Sections:**
-
-1. **Status**: Use current date and status from frontmatter
-
-2. **Context**:
-   - Summarize the problem/need
-   - List constraints discovered
-   - Include background from conversation
-
-3. **Decision**:
-   - State clearly what was chosen
-   - Include implementation approach
-   - Be specific and actionable
-
-4. **Consequences**:
-   - Positive: All benefits mentioned
-   - Negative: All trade-offs/limitations discussed
-   - Neutral: Workflow changes, dependencies, future work
-
-5. **Alternatives Considered**:
-   - List ALL options discussed (minimum 2-3)
-   - Include pros/cons for each
-   - State specific rejection reasons
-
-6. **Validation**:
-   - List any prototypes built
-   - Include benchmark results
-   - Note success criteria met
-   - Reference test code if created
-
-7. **References**:
-   - Link to relevant code files
-   - Link to documentation
-   - Link to external resources mentioned
-   - Link to related ADRs
-
-8. **Notes**:
-   - Future considerations discussed
-   - Open questions
-   - Follow-up items
-
-### Step 4: File Naming
-
-Format: `NNNN-decision-title-in-kebab-case.md`
-
-Example conversions:
-- "Use PostgreSQL" → `0042-use-postgresql-for-data-storage.md`
-- "Migrate to Kubernetes" → `0043-migrate-to-kubernetes-from-docker-swarm.md`
-- "Implement Event Sourcing" → `0044-implement-event-sourcing-pattern.md`
-
-### Step 5: Save and Confirm
-
-1. Save to `docs/adr/NNNN-title.md`
-2. Tell user: "I've created ADR-NNNN: [title] and saved it to docs/adr/"
-3. Offer to make adjustments if needed
-
-## Quality Checklist
-
-Before finalizing an ADR, verify:
-
-- [ ] All YAML frontmatter fields are filled
-- [ ] Status is appropriate (proposed vs accepted)
-- [ ] Context explains WHY this decision is needed
-- [ ] Decision is clear and specific
-- [ ] At least 2-3 alternatives are documented
-- [ ] Each alternative has pros, cons, and rejection reason
-- [ ] All three consequence types are considered
-- [ ] Validation section has concrete data (not generic)
-- [ ] References are actual links (not placeholders)
-- [ ] No TODO or FIXME comments remain
-- [ ] Markdown formatting is correct
-- [ ] File name matches convention
-- [ ] ADR number is sequential
-
-## Example Workflows
-
-### Workflow 1: Database Selection
-```
-User: "Should we use PostgreSQL or MongoDB?"
-[Discussion of requirements, trade-offs]
-User: "Let's go with PostgreSQL"
-
-Claude:
-1. Recognize this as a database selection decision
-2. Extract all discussed points
-3. Create ADR-NNNN with:
-   - Context: Data requirements, team skills
-   - Decision: PostgreSQL chosen
-   - Alternatives: MongoDB (rejected), MySQL (not discussed but include)
-   - Validation: Any performance tests mentioned
-4. Save and confirm
-```
-
-### Workflow 2: Framework Migration
-```
-User: "We need to migrate from Vue to React"
-[Discussion of reasons, timeline, risks]
-
-Claude:
-1. Recognize this as a framework decision + migration
-2. Note this might supersede an old ADR
-3. Create ADR-NNNN with:
-   - Context: Why migration is needed
-   - Decision: Migrate to React
-   - Alternatives: Stay with Vue, try Svelte
-   - Consequences: Migration cost, team training, etc.
-4. Check if previous Vue ADR exists
-5. Update old ADR status if found
-6. Save and confirm
-```
-
-### Workflow 3: New Architecture Pattern
-```
-User: "Let's implement event sourcing for audit logs"
-
-Claude:
-1. Recognize this as an architecture pattern decision
-2. Create ADR-NNNN with:
-   - Context: Audit requirements, compliance needs
-   - Decision: Implement event sourcing
-   - Alternatives: Traditional logging, database triggers
-   - Implementation: High-level approach
-3. Include in Validation: Need to build proof of concept
-4. Save and confirm
-```
-
-## Common Pitfalls to Avoid
-
-❌ **Don't**: Leave sections empty or with "TODO"
-✅ **Do**: Fill all sections or write "N/A - [reason]"
-
-❌ **Don't**: Write vague decisions like "Use a database"
-✅ **Do**: Be specific "Use PostgreSQL 15+ for transactional data storage"
-
-❌ **Don't**: Only list the chosen alternative
-✅ **Do**: Document all options discussed, even if briefly
-
-❌ **Don't**: Generic consequences like "Better performance"
-✅ **Do**: Specific consequences "Reduces query time by 40% based on benchmark"
-
-❌ **Don't**: Forget to update old ADRs when superseding
-✅ **Do**: Update both old and new ADRs with cross-references
-
-❌ **Don't**: Use present tense ("We are deciding...")
-✅ **Do**: Use past/declarative tense ("We decided..." or "We will use...")
-
-## Template Shortcuts
-
-For common decision types, use these patterns:
-
-### Technology Selection
-```
-Context: Need for [capability], evaluated based on [criteria]
-Decision: Selected [technology] for [use case]
-Alternatives: [Tech A] (rejected: reason), [Tech B] (rejected: reason)
-Validation: [Prototype/benchmark results]
-```
-
-### Migration Decision
-```
-Context: Current [old tech] limitations: [list]
-Decision: Migrate from [old] to [new] over [timeframe]
-Alternatives: Stay with current (rejected: why), [other option]
-Consequences: Migration cost [X], training [Y], benefits [Z]
-```
-
-### Architecture Pattern
-```
-Context: System requirements: [list], current problems: [list]
-Decision: Implement [pattern] for [components]
-Alternatives: [Pattern A] (rejected: why), continue current (rejected: why)
-Validation: Proof of concept in [location]
-```
-
-## Final Notes
-
-- **Trust the conversation**: All the information needed is usually in the discussion
-- **Be comprehensive**: Better to over-document than under-document
-- **Stay objective**: Present facts, not opinions
-- **Be helpful**: Offer to create ADR even if not explicitly requested
-- **Update history**: Keep track of superseded ADRs
-
-When in doubt, ask the user: "Would you like me to create an ADR to document this decision?"