astragentic 1.0.0

package/assets/_astraler/workflows/change.md

@@ -0,0 +1,210 @@
+# Change Workflow
+
+> New requirement: capture → analyze impact → update docs → regenerate tasks
+
+---
+
+## When to Use
+
+- Stakeholder requests new feature or modification
+- Bug requires spec/arch change
+- Technical debt or refactor needed
+- External dependency change affects design
+
+---
+
+## Phases
+
+### Phase 1: Capture
+
+**Goal:** Document the change request
+
+**Actions:**
+1. Record change title and description
+2. Identify change type:
+   - Feature (new capability)
+   - Enhancement (modify existing)
+   - Fix (correct behavior)
+   - Refactor (technical improvement)
+3. Note source (stakeholder, bug report, tech debt)
+4. Generate CHG ID: `CHG-{YYYY-MM-DD}-{slug}`
+
+**Output:** Change record at `05-changes/impact/CHG-{ID}.md`
+
+```markdown
+---
+id: CHG-2026-01-04-add-refund-flow
+title: Add refund flow
+type: Feature
+status: Open
+domain: order
+impact: Medium
+created: 2026-01-04
+---
+
+# CHG-2026-01-04-add-refund-flow: Add refund flow
+
+## Summary
+Add ability to refund orders within 30 days
+
+**Type:** Feature
+**Source:** Stakeholder request
+**Requested:** 2026-01-04
+```
+
+---
+
+### Phase 2: Impact
+
+**Goal:** Analyze what existing docs are affected
+
+**Actions:**
+1. Search `.astraler-docs/` for related content
+2. Identify affected domains
+3. For each affected artifact:
+   - Spec: Which flows/rules change? (`02-spec/domains/{domain}.md`)
+   - Arch: Which components/contracts change? (`03-arch/domains/{domain}.arch.md`)
+   - Tasks: Which existing tasks are impacted? (`04-tasks/domains/{domain}.tasks.md`)
+4. Classify impact level:
+   - **Low:** Single domain, no contract changes
+   - **Medium:** Single domain, contract changes
+   - **High:** Multi-domain or breaking changes
+
+**Mermaid Diagram Required:**
+```mermaid
+flowchart TD
+    CHG[CHG-ID] --> S1[Affected Spec]
+    CHG --> A1[Affected Arch]
+    CHG --> T1[Affected Tasks]
+    style CHG fill:#fff3e0
+```
+
+**Output:** Impact analysis in CHG record with visual diagram
+
+```markdown
+## Impact Analysis
+
+**Affected Domains:** order, payment
+**Impact Level:** Medium
+
+### Affected Artifacts
+| File | Section | Change Type |
+|------|---------|-------------|
+| 02-spec/domains/order.md | flows | Add refund flow |
+| 03-arch/domains/order.arch.md | contracts | New endpoint |
+| 03-arch/domains/payment.arch.md | contracts | Refund integration |
+
+### Breaking Changes
+- None (additive only)
+
+### ADR Required?
+- No (no architectural decision needed)
+```
+
+**Human Gate:** Confirm impact assessment before proceeding
+
+---
+
+### Phase 3: Update
+
+**Goal:** Modify affected documentation
+
+**Actions:**
+1. For each affected artifact:
+   - If `Approved`: Check CHG is recorded, then edit
+   - If `Draft`: Edit directly
+2. Update spec flows/rules as needed
+3. Update arch contracts/components as needed
+4. Bump version numbers appropriately:
+   - Patch: Clarification only
+   - Minor: New flow within scope
+   - Major: Contract/boundary change
+5. Add change reference to doc headers
+
+**Output:** Updated documentation with CHG traceability
+
+---
+
+### Phase 4: Replan
+
+**Goal:** Regenerate or update tasks
+
+**Actions:**
+1. Identify tasks that are:
+   - **New:** Required by the change
+   - **Modified:** Scope changed
+   - **Obsolete:** No longer needed
+2. Generate new tasks with proper refs in `04-tasks/domains/{domain}.tasks.md`
+3. Update existing task descriptions/AC
+4. Mark obsolete tasks as `CANCELLED`
+5. Update `04-tasks/milestones.md` if epic-level change
+
+**Update Task Diagrams:**
+When tasks change, update the task file diagrams:
+- **`pie` chart:** Update counts for TODO/DOING/DONE/CANCELLED
+- **`flowchart`:** Add new task nodes, update styles for changed status
+
+**Output:** Updated task backlog with refreshed diagrams
+
+```markdown
+## Task Changes
+
+### New Tasks
+- TSK-order-015: Implement refund endpoint
+- TSK-order-016: Add refund validation rules
+
+### Modified Tasks
+- TSK-order-008: Update order status enum (add REFUNDED)
+
+### Obsolete Tasks
+- None
+
+### Suggested Sprint
+- Add to current sprint (3 tasks, ~Medium effort)
+```
+
+---
+
+## Completion
+
+When change is fully processed:
+1. Run `/astra:verify` to check consistency
+2. Update `05-changes/changelog.md` with summary
+3. Mark CHG status as `Applied`
+4. Present change summary
+5. Suggest: review updated docs, approve if ready
+
+---
+
+## Quick Reference
+
+```
+/astra:change "Add refund flow"
+    │
+    ▼
+[1. Capture] ──► Create 05-changes/impact/CHG-*.md
+    │
+    ▼
+[2. Impact] ──► Analyze affected 02-spec, 03-arch, 04-tasks
+    │
+    ◆ Human confirms impact
+    │
+    ▼
+[3. Update] ──► Modify affected domain files
+    │
+    ▼
+[4. Replan] ──► Update 04-tasks/domains/*.tasks.md
+    │
+    ▼
+[Complete] ──► Verify + update changelog
+```
+
+---
+
+## Rules
+
+- Every edit to `Approved` doc must reference CHG
+- Multi-domain changes require explicit human approval
+- Breaking changes require ADR in `03-arch/decisions.md`
+- Version bumps follow semantic rules
+- CHG records stored in `05-changes/impact/`

package/assets/_astraler/workflows/greenfield.md

@@ -0,0 +1,415 @@
+# Greenfield Workflow
+
+> Atlas-first: analyze everything → generate complete atlas → auto-expand to full structure
+
+---
+
+## When to Use
+
+- New project with no existing code
+- Have stakeholder documents, notes, or requirements
+- Need complete project blueprint before building
+
+---
+
+## Flow Overview
+
+```
+/astra:start
+       │
+       ▼
+   [1. Assess]
+       │
+       ├── Detailed ────────────────┐
+       │                            │
+       │ Vague                      │
+       ▼                            │
+   [2. Discover]                    │
+       │                            │
+       ◆ Cognitive Sync             │
+       │ (ALL domains, ALL flows)   │
+       │                            │
+       └────────────────────────────┘
+                    │
+                    ▼
+      [3. Generate Complete Atlas]
+                    │
+              ◆ Human Approves Atlas
+                    │
+                    ▼
+      [4. Auto-Expand to Full Structure]
+                    │
+                    ▼
+            [Ready to Build]
+```
+
+**Key principle:** Analyze everything upfront, generate everything at once. No per-domain iteration.
+
+---
+
+## Phase 1: Assess
+
+**Goal:** Evaluate input quality and determine path
+
+**Actions:**
+1. User provides raw materials (docs, specs, notes, diagrams)
+2. Inventory all provided materials
+3. Evaluate completeness against criteria
+
+**Assessment Criteria:**
+
+| Signal | Detailed | Vague |
+|--------|----------|-------|
+| Entities | Tables/fields specified | "We need users" |
+| Screens | Specific pages listed | "A dashboard" |
+| API | Endpoints documented | "REST API" |
+| Tech stack | Already decided | Open question |
+| Business rules | Edge cases covered | Happy path only |
+| Data relationships | FK/references clear | Implied only |
+
+**Path Selection:**
+- **3+ Detailed signals** → Skip to Phase 3 (Generate Atlas)
+- **Otherwise** → Phase 2 (Discover)
+
+---
+
+## Phase 2: Discover (If Needed)
+
+**Goal:** Build complete understanding of ALL domains through dialogue
+
+**Actions:**
+1. Read provided materials thoroughly
+2. Identify ALL domains, ALL flows, ALL entities
+3. Generate targeted questions for gaps
+4. Iterate Q&A until complete understanding
+5. Present Cognitive Sync Checkpoint
+
+### Cognitive Sync Checkpoint
+
+Validate complete understanding before generation:
+
+```markdown
+## My Understanding
+
+### What We're Building
+{1-2 sentence summary}
+
+### Tech Stack
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| Runtime | {choice} | {why} |
+| Database | {choice} | {why} |
+| Framework | {choice} | {why} |
+
+### All Domains Identified
+| Domain | Purpose | Priority | Key Entities |
+|--------|---------|----------|--------------|
+| {domain} | {purpose} | P0/P1/P2 | {entities} |
+{repeat for ALL domains}
+
+### All Screens Identified
+| Screen | Route | Domain | Auth |
+|--------|-------|--------|------|
+{ALL screens listed}
+
+### All Key Flows
+1. {flow}: {steps summary}
+{ALL major flows listed}
+
+### All Core Entities
+| Entity | Domain | Key Fields |
+|--------|--------|------------|
+{ALL entities listed}
+
+### What We're NOT Building
+- {anti-goal}: {why excluded}
+
+---
+**Is this complete and correct?**
+[y] Yes, generate Atlas | [n] No, let me clarify | [p] Partially, refine
+```
+
+**Human Gate:** Confirm complete understanding before Atlas generation
+
+---
+
+## Phase 3: Generate Complete Atlas
+
+**Goal:** Produce comprehensive project blueprint covering ALL domains
+
+**Actions:**
+1. Create `.astraler-docs/` folder structure
+2. Generate complete `atlas/` folder
+3. Generate supporting files
+
+### Atlas Folder Structure
+
+```
+.astraler-docs/
+├── _index.md
+├── atlas/
+│   ├── index.md             # Vision, tech stack, ALL domains
+│   ├── database.md          # Complete schema, ALL entities
+│   ├── screens.md           # ALL screens, ALL domains
+│   ├── api.md               # ALL endpoints, ALL domains
+│   └── tasks.md             # ALL tasks, ALL domains
+├── context/
+│   ├── constraints.md
+│   ├── assumptions.md
+│   └── glossary.md
+├── changes/
+│   ├── changelog.md
+│   └── impact/
+└── ai/
+    ├── guardrails.md
+    └── quality_gates.md
+```
+
+### Atlas File Specifications
+
+#### `atlas/index.md`
+- Project vision and success metrics
+- Complete tech stack table
+- ALL domains with purpose and priority
+- Domain relationship diagram (Mermaid)
+- Project structure (folder tree)
+- External integrations
+
+#### `atlas/database.md`
+- Complete ERD (Mermaid) showing ALL entities
+- ALL tables with columns, types, constraints
+- ALL relationships and foreign keys
+- ALL indexes
+- Cross-domain references
+- Migration strategy
+
+#### `atlas/screens.md`
+- Navigation map (Mermaid) showing ALL screens
+- ALL screens table (route, domain, auth)
+- Screen details for each (purpose, components, actions, API calls)
+
+#### `atlas/api.md`
+- Base URL and authentication
+- ALL endpoints summary table
+- Endpoint details for each (request, response, errors)
+- Webhooks (if applicable)
+- Rate limiting
+
+#### `atlas/tasks.md`
+- Milestone overview (Mermaid gantt)
+- Task dependency graph (Mermaid flowchart)
+- ALL tasks with ID, domain, dependencies, acceptance criteria
+- Definition of Done
+
+---
+
+### Human Gate: Atlas Approval
+
+After Atlas generation, present for review:
+
+```markdown
+## Atlas Complete
+
+### Generated Files
+- `atlas/index.md` — {X} domains, tech stack defined
+- `atlas/database.md` — {Y} tables, {Z} relationships
+- `atlas/screens.md` — {W} screens across all domains
+- `atlas/api.md` — {V} endpoints across all domains
+- `atlas/tasks.md` — {U} tasks in {T} phases
+
+### Domains Covered
+| Domain | Entities | Screens | Endpoints | Tasks |
+|--------|----------|---------|-----------|-------|
+| {domain} | {count} | {count} | {count} | {count} |
+{ALL domains listed}
+
+### Ready to Expand
+Upon approval, will auto-generate:
+- 02-spec/core/* (3 files)
+- 02-spec/domains/* ({N} files)
+- 03-arch/* (3 files + {N} domain files)
+- 04-tasks/* (1 file + {N} domain files)
+
+---
+**Approve Atlas?**
+[y] Yes, expand to full structure | [e] Edit specific file | [r] Redo section
+```
+
+---
+
+## Phase 4: Auto-Expand to Full Structure
+
+**Goal:** Automatically generate complete Astraler Docs structure from Atlas
+
+**This phase is automatic — no human iteration required.**
+
+### Expansion Mapping
+
+| Atlas Source | Generates |
+|--------------|-----------|
+| `atlas/index.md` | `02-spec/core/overview.md` |
+| `atlas/index.md` | `03-arch/overview.md` |
+| `atlas/index.md` (domains) | `02-spec/domains/{domain}.md` (overview section) |
+| `atlas/database.md` | `03-arch/data-schema.md` |
+| `atlas/database.md` (per domain) | `03-arch/domains/{domain}.arch.md` (data models) |
+| `atlas/screens.md` (per domain) | `02-spec/domains/{domain}.md` (screens section) |
+| `atlas/api.md` (cross-domain) | `02-spec/core/flows.md` |
+| `atlas/api.md` (per domain) | `02-spec/domains/{domain}.md` (API section) |
+| `atlas/api.md` (per domain) | `03-arch/domains/{domain}.arch.md` (contracts) |
+| `atlas/tasks.md` (milestones) | `04-tasks/milestones.md` |
+| `atlas/tasks.md` (per domain) | `04-tasks/domains/{domain}.tasks.md` |
+
+### Generated Structure
+
+```
+.astraler-docs/
+├── _index.md
+├── atlas/                          # SOURCE (human-approved)
+│   ├── index.md
+│   ├── database.md
+│   ├── screens.md
+│   ├── api.md
+│   └── tasks.md
+│
+├── 02-spec/                        # AUTO-GENERATED from Atlas
+│   ├── _index.md
+│   ├── core/
+│   │   ├── overview.md            # ← from atlas/index.md
+│   │   ├── flows.md               # ← from atlas/api.md (cross-domain)
+│   │   └── rules.md               # ← from atlas/api.md (validation)
+│   └── domains/
+│       ├── auth.md                # ← from atlas (auth sections)
+│       ├── catalog.md             # ← from atlas (catalog sections)
+│       ├── order.md               # ← from atlas (order sections)
+│       └── ...                    # One per domain
+│
+├── 03-arch/                        # AUTO-GENERATED from Atlas
+│   ├── _index.md
+│   ├── overview.md                # ← from atlas/index.md
+│   ├── data-schema.md             # ← from atlas/database.md
+│   ├── standards.md               # ← generated (DoD, conventions)
+│   ├── decisions.md               # ← generated (ADR template)
+│   └── domains/
+│       ├── auth.arch.md           # ← from atlas (auth sections)
+│       ├── catalog.arch.md        # ← from atlas (catalog sections)
+│       ├── order.arch.md          # ← from atlas (order sections)
+│       └── ...                    # One per domain
+│
+├── 04-tasks/                       # AUTO-GENERATED from Atlas
+│   ├── _index.md
+│   ├── milestones.md              # ← from atlas/tasks.md
+│   └── domains/
+│       ├── auth.tasks.md          # ← from atlas/tasks.md (auth)
+│       ├── catalog.tasks.md       # ← from atlas/tasks.md (catalog)
+│       ├── order.tasks.md         # ← from atlas/tasks.md (order)
+│       └── ...                    # One per domain
+│
+├── 05-changes/
+│   ├── _index.md
+│   ├── changelog.md
+│   └── impact/
+│
+├── context/
+│   ├── constraints.md
+│   ├── assumptions.md
+│   └── glossary.md
+│
+└── ai/
+    ├── guardrails.md
+    └── quality_gates.md
+```
+
+### Expansion Rules
+
+1. **All generated files include proper headers** (status, version, owner)
+2. **All generated files include required Mermaid diagrams**
+3. **All generated files are marked `status: Draft`** (human can approve later)
+4. **Atlas remains the source of truth** — changes flow Atlas → expanded files
+5. **Cross-references are maintained** between files
+
+### Post-Expansion Summary
+
+```markdown
+## Expansion Complete
+
+### Files Generated
+| Folder | Files | From Atlas |
+|--------|-------|------------|
+| 02-spec/core/ | 3 | index.md, api.md |
+| 02-spec/domains/ | {N} | All atlas files |
+| 03-arch/ | 4 | index.md, database.md |
+| 03-arch/domains/ | {N} | database.md, api.md |
+| 04-tasks/ | 1 | tasks.md |
+| 04-tasks/domains/ | {N} | tasks.md |
+| **Total** | **{total}** | |
+
+### Ready to Build
+- Start with: `04-tasks/domains/{first-priority-domain}.tasks.md`
+- Reference: `atlas/` for complete picture
+- Changes: Use `/astra:change` to modify approved docs
+```
+
+---
+
+## Completion
+
+After expansion:
+1. **Atlas** = Source of truth (Approved status)
+2. **Expanded files** = Detailed views (Draft status, can be approved individually)
+3. **Implementation** = Start from `04-tasks/`
+4. **Changes** = Modify Atlas first, re-expand affected sections
+
+---
+
+## Quick Reference
+
+```
+/astra:start
+       │
+       ▼
+[1. Assess] ─── Detailed? ───┐
+       │                     │
+       │ Vague               │
+       ▼                     │
+[2. Discover]                │
+       │                     │
+       ◆ Cognitive Sync      │
+       │                     │
+       └─────────────────────┘
+                │
+                ▼
+   [3. Generate Atlas]
+                │
+          ◆ Human Approves
+                │
+                ▼
+   [4. Auto-Expand]
+                │
+                ▼
+       [Ready to Build]
+```
+
+---
+
+## Checklist
+
+### Before Atlas Generation
+- [ ] All domains identified
+- [ ] All key flows understood
+- [ ] All core entities recognized
+- [ ] Tech stack decided
+- [ ] Cognitive Sync confirmed
+
+### Atlas Files Complete
+- [ ] `atlas/index.md` — All domains, tech stack
+- [ ] `atlas/database.md` — All entities, relationships
+- [ ] `atlas/screens.md` — All screens, navigation
+- [ ] `atlas/api.md` — All endpoints, contracts
+- [ ] `atlas/tasks.md` — All tasks, dependencies
+
+### After Expansion
+- [ ] `02-spec/` — Core + all domain specs
+- [ ] `03-arch/` — Overview + all domain arch
+- [ ] `04-tasks/` — Milestones + all domain tasks
+- [ ] All files have proper headers
+- [ ] All files have required diagrams