astragentic 1.0.0

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

@@ -0,0 +1,200 @@
+---
+description: "Create or update domain specification"
+argument-hint: "<domain>"
+allowed-tools: ["Read", "Write", "Edit", "Glob"]
+---
+
+Creates or updates a business requirements specification 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 spec
+
+## Prerequisites
+
+- `.astraler-docs/01-context/product.md` exists
+- Domain is within project scope
+
+## Reads
+
+- `.astraler-docs/01-context/product.md` (priorities, constraints)
+- `.astraler-docs/02-spec/domains/{domain}.md` (if updating)
+- User-provided requirements
+
+## Writes
+
+- `.astraler-docs/02-spec/domains/{domain}.md`
+
+## Mermaid Diagram Requirements
+
+Every spec MUST include these diagrams:
+
+| Diagram Type | Section | Purpose |
+|--------------|---------|---------|
+| `sequenceDiagram` | Flows | Show actor interactions step-by-step |
+| `stateDiagram-v2` | Flows | Show entity state transitions |
+| `erDiagram` | Data Requirements | Show entity relationships |
+
+**Optional but recommended:**
+- `flowchart` for decision trees in complex flows
+- `pie` for priority distribution visualization
+
+## Spec Structure
+
+```markdown
+---
+doc: {domain}-spec
+domain: {domain}
+status: Draft
+owner: astra-ba
+version: v1.0
+change-id: CHG-INIT
+last-updated: {YYYY-MM-DD}
+---
+
+# {Domain} Specification
+
+## Purpose
+Why this domain exists.
+
+## Actors
+
+| Actor | Type | Description |
+|-------|------|-------------|
+| {name} | {Primary/System} | {role} |
+
+## Flows
+
+### Flow 1: {Flow Name}
+
+```mermaid
+sequenceDiagram
+    participant A as Actor
+    participant S as System
+    A->>S: Action
+    S-->>A: Response
+```
+
+**Preconditions:** {list}
+
+**Steps:**
+1. Step one
+2. Step two
+
+**Postconditions:** {list}
+
+### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> State1
+    State1 --> State2: trigger
+    State2 --> [*]
+```
+
+## Business Rules
+
+| ID | Rule | Applies To | Enforcement |
+|----|------|------------|-------------|
+| BR-01 | {description} | {flow/entity} | {how enforced} |
+
+## Edge Cases
+
+| ID | Condition | Response | HTTP Code |
+|----|-----------|----------|-----------|
+| EC-01 | {condition} | {error message} | {code} |
+
+## Data Requirements
+
+```mermaid
+erDiagram
+    ENTITY1 ||--o{ ENTITY2 : contains
+    ENTITY1 {
+        uuid id PK
+        string name
+    }
+    ENTITY2 {
+        uuid id PK
+        uuid entity1_id FK
+    }
+```
+
+| Entity | Description | Key Fields |
+|--------|-------------|------------|
+| {Entity} | {purpose} | {fields} |
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+## Update Mode
+
+If spec exists and is `Approved`:
+- Require CHG reference
+- Bump version appropriately
+
+If spec exists and is `Draft`:
+- Edit directly
+- Note changes made
+
+## Execution Pattern (Checkpoints)
+
+Generate spec in sections with save-after-each pattern:
+
+```
+1. Generate Purpose + Actors
+   → Save to file
+   → Present: "Purpose and Actors defined. [c] Continue | [e] Edit | [q] Quit"
+
+2. Generate Flows (with sequenceDiagram, stateDiagram-v2)
+   → Save to file
+   → Present each diagram for review (see Interactive Diagram Review)
+   → Confirm: [c] Continue | [e] Edit
+
+3. Generate Business Rules + Edge Cases
+   → Save to file
+   → Confirm: [c] Continue | [e] Edit
+
+4. Generate Data Requirements (with erDiagram)
+   → Save to file
+   → Present diagram for review
+   → Confirm: [c] Continue | [e] Edit
+
+5. Generate Success Criteria
+   → Save to file
+   → Present complete spec for final review
+```
+
+This prevents losing work and enables iterative refinement.
+
+## Interactive Diagram Review
+
+After generating each required Mermaid diagram, present for validation:
+
+```markdown
+## Sequence Diagram: {Flow Name}
+
+```mermaid
+sequenceDiagram
+    participant A as Actor
+    participant S as System
+    A->>S: Action
+    S-->>A: Response
+```
+
+**Does this accurately represent the flow?**
+[y] Yes, continue | [e] Edit this diagram | [s] Skip (will flag in verify)
+```
+
+Repeat for each diagram type:
+- `sequenceDiagram` for each flow
+- `stateDiagram-v2` for state transitions
+- `erDiagram` for data relationships
+
+## Output
+
+Confirm spec created/updated with summary of content and diagrams included.

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

@@ -0,0 +1,86 @@
+---
+description: "Start Astra: detect project state and launch appropriate workflow"
+argument-hint: "[--scan]"
+allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep"]
+---
+
+Entry point for Astra. Detects whether this is a greenfield or brownfield situation.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Detect project state (see below)
+3. Load and execute appropriate workflow
+
+## Detection Logic
+
+```
+Check .astraler-docs/ exists?
+├── No → Check for existing codebase (src/, app/, lib/)
+│         ├── Yes (or --scan flag) → BROWNFIELD
+│         └── No → GREENFIELD
+└── Yes → Check for 02-spec/domains/ content
+          ├── Empty → GREENFIELD (continue from distill)
+          └── Has content → Already initialized, suggest specific command
+```
+
+## Greenfield Path
+
+Load `@_astraler/workflows/greenfield.md` and execute:
+1. Ingest raw materials
+2. Brainstorm requirements
+3. Distill into product.md
+4. Design each domain
+
+## Brownfield Path
+
+Load `@_astraler/workflows/brownfield.md` and execute:
+1. Scan codebase structure
+2. Sketch draft documentation
+3. Validate with human
+4. Normalize to standard format
+
+## Bootstrap
+
+If `.astraler-docs/` doesn't exist, create the full structure:
+
+```
+.astraler-docs/
+├── _index.md
+├── 01-context/
+│   ├── _index.md
+│   ├── product.md
+│   ├── constraints.md
+│   ├── assumptions.md
+│   └── glossary.md
+├── 02-spec/
+│   ├── _index.md
+│   ├── core/
+│   │   ├── overview.md
+│   │   ├── flows.md
+│   │   └── rules.md
+│   └── domains/
+├── 03-arch/
+│   ├── _index.md               # Navigation only
+│   ├── overview.md             # System architecture, tech stack
+│   ├── data-schema.md          # Global database schema
+│   ├── decisions.md
+│   ├── standards.md
+│   └── domains/
+├── 04-tasks/
+│   ├── _index.md
+│   ├── milestones.md
+│   ├── domains/
+│   └── sprints/
+├── 05-changes/
+│   ├── _index.md
+│   ├── changelog.md
+│   └── impact/
+└── ai/
+    ├── guardrails.md
+    └── quality_gates.md
+```
+
+## Output
+
+Report which workflow was selected and current phase.

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

@@ -0,0 +1,135 @@
+---
+description: "Show project status and suggest next action"
+argument-hint: "[domain]"
+allowed-tools: ["Read", "Glob"]
+---
+
+Read-only status check for project state and guidance on next steps.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Check if `.astraler-docs/` exists
+3. Analyze artifact states
+4. Suggest next action
+
+## Detection Logic
+
+```
+Check .astraler-docs/ exists?
+├── No → Suggest: /astra:start
+└── Yes → Analyze artifacts
+          ├── No specs → Phase: Context (run /astra:spec)
+          ├── Specs but no arch → Phase: Design (run /astra:arch)
+          ├── Arch but no tasks → Phase: Planning (run /astra:plan)
+          ├── Tasks exist → Phase: Implementation
+          └── Check for pending CHGs
+```
+
+## Artifact Analysis
+
+For each domain found in `02-spec/domains/`:
+1. Check spec exists and status (Draft/Approved)
+2. Check arch exists and status
+3. Check tasks exist and status
+4. Count task states (TODO/DOING/DONE/BLOCKED)
+
+## Status Indicators
+
+| Symbol | Meaning |
+|--------|---------|
+| `✅` | Approved |
+| `📝` | Draft |
+| `⚠️` | Needs attention (stale, missing refs) |
+| `⬜` | Missing |
+| `🔄` | In progress (DOING tasks) |
+
+## Output Format
+
+```markdown
+# Astra Project Status
+
+**Project:** {from 01-context/product.md title or folder name}
+**Phase:** {Context | Design | Planning | Implementation | Maintenance}
+**Last activity:** {most recent file modification date}
+
+---
+
+## Artifact Matrix
+
+| Domain | Spec | Arch | Tasks | Progress |
+|--------|------|------|-------|----------|
+| {domain} | {status} | {status} | {status} | {n/m done} |
+
+---
+
+## Task Summary
+
+| Status | Count |
+|--------|-------|
+| TODO | {n} |
+| DOING | {n} |
+| DONE | {n} |
+| BLOCKED | {n} |
+
+---
+
+## Pending Changes
+
+| CHG ID | Title | Status |
+|--------|-------|--------|
+| {id} | {title} | {Open/Applied} |
+
+---
+
+## Suggested Next Action
+
+→ `{command}` — {reason}
+
+**Alternative actions:**
+- `{command}` — {reason}
+- `{command}` — {reason}
+```
+
+## Phase Determination
+
+| Condition | Phase | Primary Action |
+|-----------|-------|----------------|
+| No `.astraler-docs/` | Not initialized | `/astra:start` |
+| No `01-context/product.md` | Context | `/astra:start` |
+| No specs in `02-spec/domains/` | Context | `/astra:spec <domain>` |
+| Specs exist, no arch | Design | `/astra:arch <domain>` |
+| Arch exists, no tasks | Planning | `/astra:plan <domain>` |
+| Tasks exist, some TODO | Implementation | `/astra:build <domain>` |
+| All tasks DONE | Maintenance | `/astra:verify` |
+| Open CHG records | Change in progress | `/astra:change` (continue) |
+
+## Domain-Specific View
+
+If domain argument provided:
+
+```markdown
+# {Domain} Status
+
+**Spec:** {path} — {status}
+**Arch:** {path} — {status}
+**Tasks:** {path} — {n} total
+
+## Task Breakdown
+
+| ID | Title | Status | Deps |
+|----|-------|--------|------|
+| TSK-{domain}-001 | {title} | {status} | {deps} |
+
+## Blockers
+
+- {list any BLOCKED tasks with reason}
+
+## Next Action
+
+→ `{specific command for this domain}`
+```
+
+## No Modifications
+
+This command is READ-ONLY. It analyzes but does not change files.

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

@@ -0,0 +1,139 @@
+---
+description: "Verify documentation consistency and quality"
+argument-hint: "[domain|--all]"
+allowed-tools: ["Read", "Glob", "Grep"]
+---
+
+Read-only verification of documentation consistency.
+
+## Activation
+
+1. LOAD engine rules from `@_astraler/engine.md`
+2. Parse scope (domain or --all)
+3. Run verification checks
+4. Report findings
+
+## Scope
+
+| Input | Checks |
+|-------|--------|
+| `order` | Single domain |
+| `--all` | All domains |
+| (none) | All domains |
+
+## Paths Checked
+
+- `.astraler-docs/01-context/` - Context files
+- `.astraler-docs/02-spec/domains/` - Domain specs
+- `.astraler-docs/03-arch/domains/` - Domain architectures
+- `.astraler-docs/04-tasks/domains/` - Domain tasks
+- `.astraler-docs/05-changes/impact/` - Change records
+
+## Checks Performed
+
+### 1. Spec ↔ Arch Consistency
+- Every spec flow has arch support
+- Every spec actor appears in arch
+- No orphaned arch components
+- Paths: `02-spec/domains/{domain}.md` ↔ `03-arch/domains/{domain}.arch.md`
+
+### 2. Arch ↔ Tasks Traceability
+- Every arch component has tasks
+- Every arch contract has tasks
+- No orphaned tasks
+- Paths: `03-arch/domains/{domain}.arch.md` ↔ `04-tasks/domains/{domain}.tasks.md`
+
+### 3. Task Quality
+- Has spec reference (valid path)
+- Has arch reference (valid path)
+- Has testable acceptance criteria
+- Status is valid
+
+### 4. Change Discipline
+- Approved docs not edited without CHG
+- CHG records are complete
+- Version numbers consistent
+- Check: `05-changes/impact/` records
+
+### 5. Cross-Domain
+- Shared dependencies documented
+- No circular domain dependencies
+- ADRs referenced where needed
+- Check: `03-arch/decisions.md`
+
+### 6. Mermaid Diagram Compliance
+
+Verify required diagrams exist in each document type:
+
+**Specs (`02-spec/domains/*.md`):**
+- [ ] Has `sequenceDiagram` in Flows section
+- [ ] Has `stateDiagram-v2` for state transitions
+- [ ] Has `erDiagram` in Data Requirements
+
+**Architecture (`03-arch/domains/*.arch.md`):**
+- [ ] Has `flowchart` in Overview
+- [ ] Has `classDiagram` in Components
+- [ ] Has `sequenceDiagram` in Contracts
+- [ ] Has `erDiagram` in Data Models
+- [ ] Has `stateDiagram-v2` in State Machine (if applicable)
+
+**Tasks (`04-tasks/domains/*.tasks.md`):**
+- [ ] Has `pie` chart in Summary
+- [ ] Has `flowchart` in Dependency Graph
+
+**Change Records (`05-changes/impact/CHG-*.md`):**
+- [ ] Has `flowchart` in Impact Analysis
+
+## Finding Categories
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| **Blocker** | Must fix before proceeding | Stop |
+| **Warning** | Should fix, can continue | Note |
+| **Info** | Suggestion only | Optional |
+
+## Output
+
+```markdown
+## Verification Report
+
+**Scope:** {domain|all}
+**Date:** {YYYY-MM-DD}
+
+### Summary
+
+| Category | Count |
+|----------|-------|
+| Blockers | {n} |
+| Warnings | {n} |
+| Info | {n} |
+
+### Blockers
+
+- {finding with location and fix suggestion}
+
+### Warnings
+
+- {finding with location}
+
+### Info
+
+- {finding}
+
+### Diagram Compliance
+
+| Document | Required Diagrams | Found | Missing |
+|----------|-------------------|-------|---------|
+| 02-spec/domains/{domain}.md | 3 | {n} | {list} |
+| 03-arch/domains/{domain}.arch.md | 5 | {n} | {list} |
+| 04-tasks/domains/{domain}.tasks.md | 2 | {n} | {list} |
+
+---
+
+**Result:** {PASS|BLOCKED|PASS_WITH_WARNINGS}
+```
+
+## No Modifications
+
+This command is READ-ONLY. It reports but does not fix issues.
+To fix: use `/astra:spec`, `/astra:arch`, `/astra:plan`, or `/astra:change`.

package/bin/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== 'install') {
+  console.log('Usage: npx astragentic install');
+  process.exit(0);
+}
+
+const assetsDir = path.join(__dirname, '../assets');
+const targetDir = process.cwd();
+
+console.log('🚀 Starting Astragentic installation...');
+
+// Helper to copy directory
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.error(`❌ Source directory not found: ${src}`);
+    return;
+  }
+  
+  // Use cp -r for simplicity on Unix-like systems (Mac/Linux)
+  // For Windows compatibility, a more complex recursive fs function would be needed.
+  // Given the user is on Mac, this is acceptable for now, but we can wrap it in try-catch.
+  try {
+    // Check if dest exists
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    
+    // Using cp -R to copy contents
+    // We want content of src to go into dest.
+    // If we do cp -R src dest, we might get dest/src.
+    // We want src/* -> dest/
+    
+    // Better approach: recursive copy with fs
+    copyRecursiveSync(src, dest);
+    console.log(`✅ Installed to: ${dest}`);
+  } catch (err) {
+    console.error(`❌ Error copying to ${dest}:`, err.message);
+  }
+}
+
+function copyRecursiveSync(src, dest) {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats.isDirectory();
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest);
+    }
+    fs.readdirSync(src).forEach(function(childItemName) {
+      copyRecursiveSync(path.join(src, childItemName),
+                        path.join(dest, childItemName));
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+// 1. Install .claude
+const claudeSource = path.join(assetsDir, 'claude-code');
+const claudeDest = path.join(targetDir, '.claude');
+
+console.log('📦 Installing .claude configuration...');
+copyDir(claudeSource, claudeDest);
+
+// 2. Install _astraler
+const astralerSource = path.join(assetsDir, '_astraler');
+const astralerDest = path.join(targetDir, '_astraler');
+
+console.log('📦 Installing _astraler resources...');
+copyDir(astralerSource, astralerDest);
+
+console.log('🎉 Astragentic installation complete!');
+console.log('👉 You can now run "claude" to start the agent.');

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "astragentic",
+  "version": "1.0.0",
+  "description": "Installer for Astragentic devkit",
+  "bin": {
+    "astragentic": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Astraler Team",
+  "license": "ISC",
+  "dependencies": {}
+}