astragentic 1.0.0

package/assets/claude-code/CLAUDE-TEMPLATE.md

@@ -0,0 +1,185 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+**Project Name:** [CUSTOMIZE: Your project name]
+
+**Description:** [CUSTOMIZE: Brief project description]
+
+---
+
+## Framework Architecture
+
+Astragentic operates through three interconnected roots:
+
+| Root | Location | Purpose |
+|------|----------|---------|
+| **Artifacts** | `.astraler-docs/` | Source of truth for all design documents |
+| **Commands** | `.claude/commands/astra/` | AI command definitions (slash commands) |
+| **Engine** | `_astraler/` | Execution rules, workflows, and governance |
+
+```
+your-project/
+├── .astraler-docs/          # What we're building (artifacts)
+│   ├── 01-context/          # Vision, constraints, glossary
+│   ├── 02-spec/             # Business requirements by domain
+│   ├── 03-arch/             # Technical architecture by domain
+│   ├── 04-tasks/            # Implementation breakdown
+│   ├── 05-changes/          # Change records (CHG)
+│   └── ai/                  # Rules, guardrails, quality gates
+│
+├── .claude/                 # AI operating system
+│   └── commands/astra/      # Slash command definitions
+│
+└── _astraler/               # Framework engine
+    ├── engine.md            # Core execution rules
+    └── workflows/           # greenfield, brownfield, change
+```
+
+---
+
+## Project Documentation
+
+All project documentation lives in `.astraler-docs/`. Read these before making changes:
+
+### Context & Vision
+- [Product Vision](.astraler-docs/01-context/product.md) - North star, priorities, anti-goals
+- [Constraints](.astraler-docs/01-context/constraints.md) - Technical & business boundaries
+- [Assumptions](.astraler-docs/01-context/assumptions.md) - Validatable assumptions
+- [Glossary](.astraler-docs/01-context/glossary.md) - Domain terminology
+
+### Technical Reference
+- [Tech Stack](.astraler-docs/03-arch/overview.md) - Technology choices, infrastructure
+- [Data Schema](.astraler-docs/03-arch/data-schema.md) - Database structure, relationships
+- [Engineering Standards](.astraler-docs/03-arch/standards.md) - DoD, code standards, testing
+- [Architecture Decisions](.astraler-docs/03-arch/decisions.md) - ADRs
+
+### Business Requirements
+- [System Overview](.astraler-docs/02-spec/core/overview.md) - Actors, scope, boundaries
+- [Business Flows](.astraler-docs/02-spec/core/flows.md) - Cross-domain processes
+- [Business Rules](.astraler-docs/02-spec/core/rules.md) - Global constraints
+
+### Implementation
+- [Milestones](.astraler-docs/04-tasks/milestones.md) - Epic-level goals
+- [Changelog](.astraler-docs/05-changes/changelog.md) - Change history
+
+### AI Governance
+- [Guardrails](.astraler-docs/ai/guardrails.md) - AI agent constraints
+- [Rules](.astraler-docs/ai/rules.md) - Development rules
+- [Quality Gates](.astraler-docs/ai/quality_gates.md) - Test taxonomy, gates
+
+---
+
+## Astra Commands
+
+### Discovery & Status
+
+| Command | Purpose |
+|---------|---------|
+| `/astra:start` | Bootstrap project or scan existing codebase |
+| `/astra:status` | Show current project state and suggest next action |
+| `/astra:help` | List available commands and workflow guidance |
+
+### Design Phase
+
+| Command | Purpose |
+|---------|---------|
+| `/astra:spec <domain>` | Create/update domain specification |
+| `/astra:arch <domain>` | Create/update domain architecture |
+| `/astra:plan <domain>` | Generate implementation tasks |
+
+### Build Phase
+
+| Command | Purpose |
+|---------|---------|
+| `/astra:build <task> [--auto]` | Implement tasks with code + tests |
+| `/astra:verify` | Check documentation consistency |
+
+### Governance
+
+| Command | Purpose |
+|---------|---------|
+| `/astra:change <title>` | Manage changes to approved docs |
+
+---
+
+## Development Rules
+
+### Before Coding
+1. Read the relevant [domain spec](.astraler-docs/02-spec/domains/) for business requirements
+2. Read the relevant [domain arch](.astraler-docs/03-arch/domains/) for technical design
+3. Check [engineering standards](.astraler-docs/03-arch/standards.md) for DoD
+
+### Code Standards
+[CUSTOMIZE: Add your coding conventions]
+
+- Follow naming conventions in [standards](.astraler-docs/03-arch/standards.md)
+- Match existing patterns in the codebase
+- [CUSTOMIZE: Additional rules]
+
+### Testing Requirements
+[CUSTOMIZE: Add your testing rules]
+
+- See [quality gates](.astraler-docs/ai/quality_gates.md) for test taxonomy
+- [CUSTOMIZE: Coverage requirements]
+- [CUSTOMIZE: Test naming conventions]
+
+### Forbidden Patterns
+[CUSTOMIZE: Add patterns to avoid]
+
+- Never edit `Approved` docs without a CHG record
+- [CUSTOMIZE: Security anti-patterns]
+- [CUSTOMIZE: Architecture violations]
+
+---
+
+## Common Commands
+
+[CUSTOMIZE: Add your build/test/run commands]
+
+```bash
+# Install dependencies
+[CUSTOMIZE]
+
+# Run tests
+[CUSTOMIZE]
+
+# Build
+[CUSTOMIZE]
+
+# Start development server
+[CUSTOMIZE]
+```
+
+---
+
+## Change Management
+
+When requirements change:
+1. Run `/astra:change "<title>"` to create a change record
+2. Wait for impact analysis and human approval
+3. Changes are applied to docs and tasks automatically
+4. Run `/astra:verify` to confirm consistency
+
+See [changelog](.astraler-docs/05-changes/changelog.md) for recent changes.
+
+---
+
+## Domain Quick Links
+
+[CUSTOMIZE: Add your domains after running /astra:spec]
+
+| Domain | Spec | Arch | Tasks |
+|--------|------|------|-------|
+| [DOMAIN] | [spec](.astraler-docs/02-spec/domains/[DOMAIN].md) | [arch](.astraler-docs/03-arch/domains/[DOMAIN].arch.md) | [tasks](.astraler-docs/04-tasks/domains/[DOMAIN].tasks.md) |
+
+---
+
+## Navigation
+
+- **New to project?** Start with [Product Vision](.astraler-docs/01-context/product.md)
+- **Understanding the system?** See [System Overview](.astraler-docs/02-spec/core/overview.md)
+- **Technical questions?** Check [Tech Stack](.astraler-docs/03-arch/overview.md) and [Data Schema](.astraler-docs/03-arch/data-schema.md)
+- **Need to implement?** See [Milestones](.astraler-docs/04-tasks/milestones.md)

package/assets/claude-code/commands/astra/arch.md

@@ -0,0 +1,311 @@
+---
+description: "Create or update domain architecture"
+argument-hint: "<domain>"
+allowed-tools: ["Read", "Write", "Edit", "Glob"]
+---
+
+Creates or updates technical architecture for a domain.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Parse domain name from arguments
+3. Check prerequisites
+4. Create or update arch
+
+## Prerequisites
+
+- `.astraler-docs/02-spec/domains/{domain}.md` exists (Draft or Approved)
+- Spec has defined flows and rules
+
+## Reads
+
+- `.astraler-docs/02-spec/domains/{domain}.md` (requirements to implement)
+- `.astraler-docs/03-arch/domains/{domain}.arch.md` (if updating)
+- `.astraler-docs/03-arch/overview.md` (system architecture, tech stack)
+- `.astraler-docs/03-arch/data-schema.md` (global database schema)
+- `.astraler-docs/03-arch/decisions.md` (existing ADRs)
+- `.astraler-docs/03-arch/standards.md` (engineering standards)
+
+## Writes
+
+- `.astraler-docs/03-arch/domains/{domain}.arch.md`
+- `.astraler-docs/03-arch/data-schema.md` (if new entities added)
+- `.astraler-docs/03-arch/decisions.md` (if ADR needed)
+
+## Mermaid Diagram Requirements
+
+Every arch doc MUST include these diagrams:
+
+| Diagram Type | Section | Purpose |
+|--------------|---------|---------|
+| `flowchart` | Overview | Show component relationships |
+| `classDiagram` | Components | Show class/service structure |
+| `sequenceDiagram` | Contracts | Show API request/response flows |
+| `erDiagram` | Data Models | Show database schema |
+| `stateDiagram-v2` | State Machine | Show entity lifecycle (if applicable) |
+
+**Optional but recommended:**
+- `flowchart` for dependency graphs
+- `sequenceDiagram` for integration flows
+
+## Arch Structure
+
+```markdown
+---
+doc: {domain}-arch
+domain: {domain}
+status: Draft
+owner: astra-arch
+version: v1.0
+change-id: CHG-INIT
+last-updated: {YYYY-MM-DD}
+spec-ref: 02-spec/domains/{domain}.md
+---
+
+# {Domain} Architecture
+
+## Overview
+
+```mermaid
+flowchart TB
+    subgraph Domain
+        CTRL[Controller]
+        SVC[Service]
+        REPO[Repository]
+    end
+
+    subgraph External
+        DB[(Database)]
+        EXT[External Service]
+    end
+
+    CTRL --> SVC --> REPO --> DB
+    SVC --> EXT
+```
+
+{High-level technical approach description}
+
+## Components
+
+```mermaid
+classDiagram
+    class Service {
+        -repository: Repository
+        +method(dto): Result
+    }
+    class Repository {
+        +create(entity): Entity
+        +findById(id): Entity
+    }
+    Service --> Repository
+```
+
+### {Component Name}
+
+| Attribute | Value |
+|-----------|-------|
+| **Purpose** | {what it does} |
+| **Technology** | {stack/framework} |
+| **Location** | `src/{domain}/{component}.ts` |
+
+**Responsibilities:**
+- Responsibility 1
+- Responsibility 2
+
+**Dependencies:**
+- {dependency} ({type})
+
+## Contracts
+
+### {Endpoint}: {METHOD} /api/v1/{path}
+
+```mermaid
+sequenceDiagram
+    Client->>API: {METHOD} /api/v1/{path}
+    API->>Service: method(dto)
+    Service->>DB: query
+    DB-->>Service: result
+    Service-->>API: response
+    API-->>Client: {status} {body}
+```
+
+**Request:**
+```typescript
+interface RequestDto {
+  field: type;
+}
+```
+
+**Response ({status}):**
+```typescript
+interface ResponseDto {
+  field: type;
+}
+```
+
+**Errors:**
+| Code | Condition |
+|------|-----------|
+| 400 | {condition} |
+| 404 | {condition} |
+
+## Data Models
+
+```mermaid
+erDiagram
+    ENTITY_NAME ||--o{ RELATED_ENTITY : contains
+    ENTITY_NAME {
+        uuid id PK
+        string field
+        timestamp created_at
+    }
+    RELATED_ENTITY {
+        uuid id PK
+        uuid entity_id FK
+        string data
+    }
+```
+
+> Replace `ENTITY_NAME`, `RELATED_ENTITY` with actual table names.
+
+### Indexes
+```sql
+CREATE INDEX idx_{table}_{field} ON {table}({field});
+```
+
+## State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> STATE1: create
+    STATE1 --> STATE2: action
+    STATE2 --> [*]: complete
+```
+
+| From | To | Trigger | Guard |
+|------|-----|---------|-------|
+| STATE1 | STATE2 | {trigger} | {condition} |
+
+## Dependencies
+
+### Internal
+| Domain | Type | Purpose |
+|--------|------|---------|
+| {domain} | sync/async | {purpose} |
+
+### External
+| Service | Purpose | Fallback |
+|---------|---------|----------|
+| {service} | {purpose} | {fallback} |
+
+## Decisions
+- [ADR-{date}-{topic}](../decisions.md#{anchor}): {summary}
+```
+
+## ADR Trigger
+
+If making a significant technical choice:
+1. Document in `03-arch/decisions.md`
+2. Reference from domain arch
+
+ADR format in decisions.md:
+```markdown
+## ADR-{YYYY-MM-DD}-{topic}
+
+**Status:** Accepted
+**Domain:** {domain}
+**Date:** {YYYY-MM-DD}
+
+### Context
+Why decision was needed
+
+### Decision
+What we chose
+
+```mermaid
+flowchart TD
+    A[Option A] --> B{Decision}
+    C[Option B] --> B
+    B --> D[Chosen: Option A]
+```
+
+### Consequences
+**Positive:** Benefits
+**Negative:** Trade-offs
+
+### Alternatives Considered
+| Alternative | Why Rejected |
+|-------------|--------------|
+| Option B | {reason} |
+```
+
+## Execution Pattern (Checkpoints)
+
+Generate architecture in sections with save-after-each pattern:
+
+```
+1. Generate Overview (with flowchart)
+   → Save to file
+   → Present diagram for review
+   → Confirm: [c] Continue | [e] Edit | [q] Quit
+
+2. Generate Components (with classDiagram)
+   → Save to file
+   → Present diagram for review
+   → Confirm: [c] Continue | [e] Edit
+
+3. Generate Contracts (with sequenceDiagram per endpoint)
+   → Save to file
+   → Present each diagram for review
+   → Confirm: [c] Continue | [e] Edit
+
+4. Generate Data Models (with erDiagram)
+   → Save to file
+   → Present diagram for review
+   → Update global data-schema.md if new entities
+   → Confirm: [c] Continue | [e] Edit
+
+5. Generate State Machine (with stateDiagram-v2)
+   → Save to file
+   → Present diagram for review
+   → Confirm: [c] Continue | [e] Edit
+
+6. Generate Dependencies + ADR refs
+   → Save to file
+   → Present complete arch for final review
+```
+
+This prevents losing work and enables iterative refinement.
+
+## Interactive Diagram Review
+
+After generating each required Mermaid diagram, present for validation:
+
+```markdown
+## Component Diagram: {Domain} Architecture
+
+```mermaid
+flowchart TB
+    subgraph Domain
+        CTRL[Controller]
+        SVC[Service]
+        REPO[Repository]
+    end
+    CTRL --> SVC --> REPO
+```
+
+**Does this accurately represent the architecture?**
+[y] Yes, continue | [e] Edit this diagram | [s] Skip (will flag in verify)
+```
+
+Repeat for each diagram type:
+- `flowchart` for component overview
+- `classDiagram` for service structure
+- `sequenceDiagram` for API contracts
+- `erDiagram` for data models
+- `stateDiagram-v2` for entity lifecycle
+
+## Output
+
+Confirm arch created/updated with component summary and diagrams included.

package/assets/claude-code/commands/astra/build.md

@@ -0,0 +1,109 @@
+---
+description: "Implement tasks: code, test, verify"
+argument-hint: "<TSK-ID|domain|--all> [--auto]"
+allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]
+---
+
+Implements one or more tasks with code and tests.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Parse input (task ID, domain, or --all)
+3. Check for `--auto` flag
+4. Select and validate tasks
+5. Implement each task
+
+## Input Modes
+
+| Input | Behavior |
+|-------|----------|
+| `TSK-order-001` | Single task |
+| `order` | All TODO tasks in domain |
+| `--all` | All TODO tasks across domains |
+| `--auto` | Skip human confirmation gates |
+
+## Execution Modes
+
+### Interactive Mode (default)
+
+- Confirm task selection before starting
+- Show progress after each task
+- Pause on failures for human decision
+
+### Auto Mode (`--auto`)
+
+- Skip confirmation gates
+- Continue on failures (log and proceed)
+- Show summary at end
+- Useful for CI/batch processing
+
+**Warning:** Auto mode will not stop for:
+- Task selection confirmation
+- Mid-implementation reviews
+- Non-critical failures
+
+It WILL stop for:
+- Missing prerequisites (spec, arch)
+- Level-B/C refactors (require CHG)
+
+## Per-Task Flow
+
+```
+1. Load task definition
+2. Validate: has spec ref, arch ref, AC
+3. Set status: TODO → DOING
+4. Read spec + arch sections
+5. Implement code
+6. Write tests
+7. Run tests
+8. If pass: Set status → DONE
+9. If fail: Keep DOING, report issue
+```
+
+## Implementation Rules
+
+- Follow arch contracts exactly
+- Stay within task scope
+- Level-A refactors allowed inline
+- Level-B/C refactors: STOP, recommend `/astra:change`
+
+## Test Requirements
+
+Based on change type:
+- **API:** Contract test + integration test
+- **Data:** Migration test + rollback test
+- **Logic:** Unit tests covering AC
+
+## Human Gate
+
+Before starting batch (if multiple tasks):
+```
+Selected {n} tasks for implementation:
+- TSK-xxx-001: {title}
+- TSK-xxx-002: {title}
+
+[c] Continue | [s] Select specific | [q] Quit
+```
+
+## Output
+
+Per task:
+```markdown
+## TSK-{domain}-{###}: {status}
+
+**Files changed:**
+- {file1} (created)
+- {file2} (modified)
+
+**Tests:**
+- {test_file}: {pass/fail}
+
+**Notes:**
+- {any refactors or issues}
+```
+
+Summary:
+- Tasks completed: X
+- Tasks failed: Y
+- Files changed: Z