@magic-ingredients/tiny-brain-local 0.10.2 → 0.12.2

package/templates/adr/README.md

@@ -0,0 +1,243 @@
+# 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/adr-schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/adr-schema.json",
+  "title": "Architecture Decision Record",
+  "description": "Schema for validating ADR YAML frontmatter",
+  "type": "object",
+  "required": ["adr_number", "title", "date", "status"],
+  "properties": {
+    "adr_number": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Sequential ADR number"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 5,
+      "maxLength": 100,
+      "description": "Brief, descriptive title of the decision"
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "Decision date in YYYY-MM-DD format"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["proposed", "accepted", "deprecated", "superseded"],
+      "description": "Current status of the ADR"
+    },
+    "supersedes": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "integer", "minimum": 1 }
+      ],
+      "description": "ADR number this decision replaces (if any)"
+    },
+    "superseded_by": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "integer", "minimum": 1 }
+      ],
+      "description": "ADR number that replaces this decision (if any)"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+$"
+      },
+      "uniqueItems": true,
+      "description": "Tags for categorizing the ADR"
+    },
+    "decision_makers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "People involved in making this decision"
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "adr_number": 42,
+      "title": "Use PostgreSQL for Data Storage",
+      "date": "2025-01-15",
+      "status": "accepted",
+      "supersedes": null,
+      "superseded_by": null,
+      "tags": ["database", "infrastructure"],
+      "decision_makers": ["Alice", "Bob", "Charlie"]
+    }
+  ]
+}

package/templates/adr/adr-template.md

@@ -0,0 +1,136 @@
+---
+# ADR Metadata (YAML Frontmatter)
+adr_number: 0
+title: "Decision Title Here"
+date: YYYY-MM-DD
+status: proposed  # proposed | accepted | deprecated | superseded
+supersedes: null  # ADR number if replacing another decision
+superseded_by: null  # ADR number if this decision was replaced
+tags: []  # e.g., [infrastructure, testing, backend]
+decision_makers: []  # People involved in the decision
+---
+
+# ADR-{adr_number}: {title}
+
+## Status
+
+**{status}** (Date: {date})
+
+<!-- Status values: proposed | accepted | deprecated | superseded -->
+<!-- If superseded, reference the new ADR: "Superseded by ADR-XXX" -->
+<!-- If superseding, reference the old ADR: "Supersedes ADR-XXX" -->
+
+## Context
+
+<!-- What is the issue we're facing? -->
+<!-- What constraints exist (technical, business, team, time)? -->
+<!-- What research/prototyping/experiments informed this decision? -->
+<!-- What problem are we trying to solve? -->
+
+### Background
+<!-- Additional context about the situation -->
+
+### Constraints
+<!-- List key constraints that influenced the decision -->
+- Constraint 1
+- Constraint 2
+
+## Decision
+
+<!-- The decision that was made - be specific and concrete -->
+<!-- Use clear, declarative language: "We will use..." -->
+
+### Implementation Details
+<!-- How will this decision be implemented? -->
+<!-- Key technical specifics -->
+
+## Consequences
+
+### Positive Consequences
+<!-- Benefits realized -->
+<!-- Problems solved -->
+- Benefit 1
+- Benefit 2
+
+### Negative Consequences
+<!-- Trade-offs accepted -->
+<!-- Technical debt incurred -->
+<!-- Limitations introduced -->
+- Trade-off 1
+- Trade-off 2
+
+### Neutral Consequences
+<!-- Future work required -->
+<!-- Dependencies created -->
+<!-- Changes to team workflow -->
+- Implication 1
+- Implication 2
+
+## Alternatives Considered
+
+### Alternative 1: {Name}
+**Description:** Brief description of this alternative
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Rejection Reason:** Why this option was not chosen
+
+---
+
+### Alternative 2: {Name}
+**Description:** Brief description of this alternative
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Rejection Reason:** Why this option was not chosen
+
+---
+
+## Validation
+
+<!-- How was this decision validated? -->
+<!-- What tests/experiments were performed? -->
+<!-- What metrics were collected? -->
+<!-- What success criteria were met? -->
+
+### Tests Performed
+- Test 1
+- Test 2
+
+### Metrics Collected
+- Metric 1: Value
+- Metric 2: Value
+
+### Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## References
+
+<!-- Links to relevant resources -->
+- [Prototype code](url)
+- [Benchmark results](url)
+- [Team discussion](url)
+- [Related documentation](url)
+
+## Notes
+
+<!-- Any additional notes, future considerations, or follow-up items -->
+
+---
+
+**Related ADRs:**
+- ADR-XXX: Related Decision
+- ADR-YYY: Another Related Decision