astragentic 1.0.0

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

@@ -0,0 +1,175 @@
+---
+description: "Manage changes to approved documentation"
+argument-hint: "<title>"
+allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep"]
+---
+
+Creates a change record and updates affected documentation.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. LOAD workflow from `@_astraler/workflows/change.md`
+3. Execute change workflow phases
+
+## Workflow Phases
+
+### Phase 1: Capture
+- Generate CHG ID: `CHG-{YYYY-MM-DD}-{slug}`
+- Record change description
+- Identify change type (feature, enhancement, fix, refactor)
+
+### Phase 2: Impact
+- Search for affected documents
+- List impacted specs, archs, tasks
+- Classify impact level (low/medium/high)
+- Check if ADR required
+
+### Phase 3: Update
+- Edit affected documents with CHG reference
+- Bump versions appropriately
+- Update cross-references
+
+### Phase 4: Replan
+- Generate new tasks if needed
+- Update existing task scope
+- Mark obsolete tasks as CANCELLED
+
+## Mermaid Diagram Requirements
+
+Every CHG record MUST include:
+
+| Diagram Type | Section | Purpose |
+|--------------|---------|---------|
+| `flowchart` | Impact Analysis | Show affected artifacts visually |
+
+**Include in CHG:**
+- Impact diagram showing which documents are affected
+- Use color coding for impact severity
+
+## CHG Record Structure
+
+File: `.astraler-docs/05-changes/impact/CHG-{YYYY-MM-DD}-{slug}.md`
+
+```markdown
+---
+id: CHG-{YYYY-MM-DD}-{slug}
+title: {Title}
+type: {feature|enhancement|fix|refactor}
+status: Open
+domain: {primary domain}
+impact: {Low|Medium|High}
+created: {YYYY-MM-DD}
+author: {user}
+---
+
+# CHG-{YYYY-MM-DD}-{slug}: {Title}
+
+> {One-line summary}
+
+## Summary
+
+**What:** {Brief description of the change}
+
+**Why:** {Reason/trigger for the change}
+
+## Impact Analysis
+
+```mermaid
+flowchart TD
+    CHG[CHG-2026-01-04-change-title]
+
+    subgraph Affected Specs
+        S1[02-spec/domains/domain.md]
+    end
+
+    subgraph Affected Arch
+        A1[03-arch/domains/domain.arch.md]
+    end
+
+    subgraph Affected Tasks
+        T1[TSK-domain-xxx]
+    end
+
+    CHG --> S1
+    CHG --> A1
+    CHG --> T1
+
+    style CHG fill:#fff3e0
+    style S1 fill:#e3f2fd
+    style A1 fill:#f3e5f5
+    style T1 fill:#e8f5e9
+```
+
+> Replace `CHG-2026-01-04-change-title`, `domain`, and task IDs with actual values.
+
+### Impact Level: {Low|Medium|High}
+
+**Rationale:** {Why this impact level}
+
+### Affected Artifacts
+
+| Artifact | Section | Change Type |
+|----------|---------|-------------|
+| 02-spec/domains/{domain}.md | {section} | {Add/Modify/Remove} |
+| 03-arch/domains/{domain}.arch.md | {section} | {Add/Modify/Remove} |
+| 04-tasks/domains/{domain}.tasks.md | {task IDs} | {Add/Modify/Cancel} |
+
+## Changes Made
+
+### 1. Specification Changes
+
+**File:** `02-spec/domains/{domain}.md`
+
+```diff
++ Added content
+- Removed content
+```
+
+### 2. Architecture Changes
+
+**File:** `03-arch/domains/{domain}.arch.md`
+
+```diff
++ Added content
+- Removed content
+```
+
+### 3. Task Changes
+
+**File:** `04-tasks/domains/{domain}.tasks.md`
+
+- **New:** {list}
+- **Modified:** {list}
+- **Cancelled:** {list}
+
+## Verification
+
+```
+{/astra:verify output}
+```
+
+## Checklist
+
+- [ ] Impact confirmed
+- [ ] Specs updated
+- [ ] Arch updated
+- [ ] Tasks replanned
+- [ ] Verification passed
+- [ ] Human approved
+```
+
+## Also Update
+
+- `.astraler-docs/05-changes/changelog.md` - Add entry to recent changes
+
+## Human Gates
+
+- After impact analysis: Confirm affected artifacts
+- After update: Review changes before proceeding
+- After completion: Approve to mark Applied
+
+## Output
+
+Change record created at `.astraler-docs/05-changes/impact/{CHG-ID}.md`
+Summary of all modifications made, including diagrams.

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

@@ -0,0 +1,240 @@
+---
+description: "List available Astra commands and workflow guidance"
+argument-hint: "[command]"
+allowed-tools: ["Read"]
+---
+
+Display available commands, their purposes, and workflow guidance.
+
+## Activation
+
+1. If command argument provided → show detailed help for that command
+2. Otherwise → show command overview and workflow
+
+## Command Overview
+
+### Discovery & Status
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/astra:start` | Bootstrap new or scan existing project | First time setup |
+| `/astra:status` | Show current project state | Check progress, find next action |
+| `/astra:help` | This help | Learn available commands |
+
+### Design Phase
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/astra:spec <domain>` | Create/update domain specification | Define business requirements |
+| `/astra:arch <domain>` | Create/update domain architecture | Design technical solution |
+| `/astra:plan <domain>` | Generate implementation tasks | Break down work |
+
+### Build Phase
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/astra:build <task>` | Implement with code + tests | Execute implementation |
+| `/astra:verify` | Check documentation consistency | Before approving, after changes |
+
+### Governance
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/astra:change <title>` | Manage changes to approved docs | Modify locked artifacts |
+
+---
+
+## Workflow Diagram
+
+```
+                    ┌─────────────────────────────────────┐
+                    │           /astra:start              │
+                    │   (Greenfield or Brownfield)        │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │         /astra:status               │
+                    │    (Check state, get guidance)      │
+                    └──────────────┬──────────────────────┘
+                                   │
+         ┌─────────────────────────┼─────────────────────────┐
+         │                         │                         │
+         ▼                         ▼                         ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  /astra:spec    │────▶│  /astra:arch    │────▶│  /astra:plan    │
+│   (Specify)     │     │   (Design)      │     │   (Plan)        │
+└─────────────────┘     └─────────────────┘     └────────┬────────┘
+                                                         │
+                                                         ▼
+                                                ┌─────────────────┐
+                                                │  /astra:build   │
+                                                │  (Implement)    │
+                                                └────────┬────────┘
+                                                         │
+                        ┌────────────────────────────────┤
+                        │                                │
+                        ▼                                ▼
+               ┌─────────────────┐              ┌─────────────────┐
+               │ /astra:verify   │              │ /astra:change   │
+               │ (Validate)      │              │ (Modify locked) │
+               └─────────────────┘              └─────────────────┘
+```
+
+---
+
+## Command Details
+
+### /astra:start
+
+```
+/astra:start [--scan]
+
+Bootstrap a new project or scan an existing codebase.
+
+Options:
+  --scan    Force brownfield mode (scan existing code)
+
+Without --scan:
+  - If no codebase exists → Greenfield workflow
+  - If codebase exists → Brownfield workflow
+
+Creates: .astraler-docs/ structure
+```
+
+### /astra:status
+
+```
+/astra:status [domain]
+
+Show project status and suggest next action.
+
+Arguments:
+  domain    (optional) Focus on specific domain
+
+Output: Artifact matrix, task summary, suggested actions
+```
+
+### /astra:spec
+
+```
+/astra:spec <domain>
+
+Create or update domain specification.
+
+Arguments:
+  domain    Domain name (e.g., order, payment, auth)
+
+Requires: 01-context/product.md exists
+Creates:  02-spec/domains/{domain}.md
+```
+
+### /astra:arch
+
+```
+/astra:arch <domain>
+
+Create or update domain architecture.
+
+Arguments:
+  domain    Domain name
+
+Requires: 02-spec/domains/{domain}.md exists
+Creates:  03-arch/domains/{domain}.arch.md
+```
+
+### /astra:plan
+
+```
+/astra:plan <domain>
+
+Generate implementation tasks from spec and arch.
+
+Arguments:
+  domain    Domain name
+
+Requires: spec + arch exist for domain
+Creates:  04-tasks/domains/{domain}.tasks.md
+```
+
+### /astra:build
+
+```
+/astra:build <target> [--auto]
+
+Implement tasks with code and tests.
+
+Arguments:
+  target    TSK-ID, domain name, or --all
+
+Options:
+  --auto    Skip human confirmation gates
+
+Examples:
+  /astra:build TSK-order-001     Single task
+  /astra:build order             All TODO tasks in domain
+  /astra:build --all             All TODO tasks
+  /astra:build order --auto      Batch mode, no confirmations
+```
+
+### /astra:verify
+
+```
+/astra:verify [domain|--all]
+
+Check documentation consistency (read-only).
+
+Arguments:
+  domain    Check specific domain
+  --all     Check all domains (default)
+
+Output: Verification report with blockers, warnings, diagram compliance
+```
+
+### /astra:change
+
+```
+/astra:change <title>
+
+Manage changes to approved documentation.
+
+Arguments:
+  title     Brief description of the change
+
+Creates: 05-changes/impact/CHG-{date}-{slug}.md
+Updates: Affected specs, archs, tasks with version bumps
+```
+
+---
+
+## Quick Reference
+
+| I want to... | Command |
+|--------------|---------|
+| Start a new project | `/astra:start` |
+| Document existing code | `/astra:start --scan` |
+| Check my progress | `/astra:status` |
+| Define requirements | `/astra:spec <domain>` |
+| Design solution | `/astra:arch <domain>` |
+| Break down work | `/astra:plan <domain>` |
+| Implement code | `/astra:build <task>` |
+| Validate docs | `/astra:verify` |
+| Modify approved docs | `/astra:change <title>` |
+
+---
+
+## Document Status Lifecycle
+
+```
+Draft → Approved → Deprecated
+  │         │
+  │         └── Locked (requires /astra:change to edit)
+  └── AI may edit freely
+```
+
+---
+
+## Getting Help
+
+- `/astra:help` — This overview
+- `/astra:help <command>` — Detailed command help
+- `/astra:status` — Current state and suggestions

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

@@ -0,0 +1,171 @@
+---
+description: "Generate implementation tasks from spec and arch"
+argument-hint: "<domain>"
+allowed-tools: ["Read", "Write", "Edit", "Glob"]
+---
+
+Generates actionable implementation tasks from domain spec and architecture.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Parse domain name from arguments
+3. Check prerequisites
+4. Generate or update tasks
+
+## Prerequisites
+
+- `.astraler-docs/02-spec/domains/{domain}.md` exists
+- `.astraler-docs/03-arch/domains/{domain}.arch.md` exists
+
+## Reads
+
+- `.astraler-docs/02-spec/domains/{domain}.md` (flows, rules, edge cases)
+- `.astraler-docs/03-arch/domains/{domain}.arch.md` (components, contracts)
+- `.astraler-docs/04-tasks/domains/{domain}.tasks.md` (if updating)
+- `.astraler-docs/04-tasks/milestones.md` (epic context)
+
+## Writes
+
+- `.astraler-docs/04-tasks/domains/{domain}.tasks.md`
+- `.astraler-docs/04-tasks/milestones.md` (if adding new epic)
+
+## Mermaid Diagram Requirements
+
+Every tasks doc MUST include these diagrams:
+
+| Diagram Type | Section | Purpose |
+|--------------|---------|---------|
+| `pie` | Summary | Show task status distribution |
+| `flowchart` | Dependency Graph | Show task dependencies |
+
+**Optional but recommended:**
+- `gantt` for sprint timeline visualization
+
+## Task Generation Logic
+
+For each spec flow:
+- Create task(s) to implement the flow
+- Reference spec section
+
+For each arch component:
+- Create task(s) to build the component
+- Reference arch section
+
+For each arch contract:
+- Create task to implement contract
+- Include test requirements
+
+## Task Structure
+
+```markdown
+---
+doc: {domain}-tasks
+domain: {domain}
+status: Draft
+owner: astra-planner
+version: v1.0
+change-id: CHG-INIT
+last-updated: {YYYY-MM-DD}
+spec-ref: 02-spec/domains/{domain}.md
+arch-ref: 03-arch/domains/{domain}.arch.md
+---
+
+# {Domain} Tasks
+
+Implementation tasks for the {Domain} domain.
+
+## Summary
+
+```mermaid
+pie title Domain Tasks Status
+    "TODO" : 5
+    "DOING" : 2
+    "DONE" : 3
+```
+
+> Replace counts with actual task numbers.
+
+| Status | Count | Tasks |
+|--------|:-----:|-------|
+| TODO | {n} | {list} |
+| DOING | {n} | {list} |
+| DONE | {n} | {list} |
+| BLOCKED | {n} | {list} |
+
+## Dependency Graph
+
+```mermaid
+flowchart TD
+    T001[TSK-domain-001] --> T002[TSK-domain-002]
+    T001 --> T003[TSK-domain-003]
+    T002 --> T004[TSK-domain-004]
+    T003 --> T004
+
+    style T001 fill:#c8e6c9
+    style T002 fill:#fff9c4
+```
+
+> Replace `domain` with actual domain name.
+
+**Legend:** 🟢 DONE | 🟡 DOING | ⚪ TODO | 🔴 BLOCKED
+
+---
+
+## Tasks
+
+### TSK-{domain}-001: {Title}
+
+**Spec:** [02-spec/domains/{domain}.md#{section}](../../02-spec/domains/{domain}.md#{section})
+**Arch:** [03-arch/domains/{domain}.arch.md#{section}](../../03-arch/domains/{domain}.arch.md#{section})
+
+**Description**
+{What needs to be done}
+
+**Acceptance Criteria**
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+**Test Expectations**
+- [ ] Unit tests for {component}
+- [ ] Integration tests for {flow}
+
+**Status:** TODO
+
+**Dependencies:** {TSK-xxx-xxx or none}
+
+---
+```
+
+## Task Statuses
+
+- `TODO` - Not started
+- `DOING` - In progress
+- `DONE` - Completed
+- `BLOCKED` - Waiting on dependency
+- `CANCELLED` - No longer needed
+
+## ID Generation
+
+Sequential per domain: `TSK-{domain}-{###}`
+
+Start from 001, increment for each new task.
+
+## Diagram Updates
+
+When task status changes:
+1. Update the `pie` chart counts
+2. Update node styles in dependency `flowchart`:
+   - DONE: `fill:#c8e6c9` (green)
+   - DOING: `fill:#fff9c4` (yellow)
+   - TODO: default (white)
+   - BLOCKED: `fill:#ffcdd2` (red)
+
+## Output
+
+Summary of tasks generated:
+- New tasks created
+- Existing tasks (if updating)
+- Total task count
+- Diagrams included