astragentic 1.0.0

package/assets/_astraler/workflows/brownfield.md

@@ -0,0 +1,582 @@
+# Brownfield Workflow
+
+> Atlas-first: scan codebase → clarify gaps → generate complete atlas → auto-expand
+
+---
+
+## When to Use
+
+- Existing codebase with little or no documentation
+- Taking over a project from another team
+- Need to understand and document what exists
+
+---
+
+## Flow Overview
+
+```
+/astra:start --scan
+       │
+       ▼
+   [1. Scan]
+       │
+       ▼
+   [2. Clarify]
+       │
+       ◆ Human fills gaps
+       │ (ALL domains, ALL flows)
+       │
+       ▼
+   [3. Generate Complete Atlas]
+       │
+       ◆ Human Approves Atlas
+       │
+       ▼
+   [4. Auto-Expand to Full Structure]
+       │
+       ▼
+   [Ready to Build]
+```
+
+**Key principle:** Scan everything, clarify once, generate everything at once. No per-domain iteration.
+
+---
+
+## Phase 1: Scan
+
+**Goal:** Analyze entire codebase comprehensively
+
+**Actions:**
+
+### 1.1 Core Structure
+1. Map directory structure
+2. Identify frameworks, languages, patterns
+3. Detect ALL domain boundaries (by folder, module, or namespace)
+4. Find entry points (main, routes, handlers)
+
+### 1.2 Database & Models
+5. Extract ALL database schemas (ORM, migrations, raw SQL)
+6. Map ALL entities and relationships
+7. Identify cross-domain data references
+
+### 1.3 API & Endpoints
+8. Detect ALL routes and endpoints
+9. Extract request/response patterns
+10. Identify authentication/authorization patterns
+
+### 1.4 Configuration & Environment
+11. Locate config files (`.env.example`, `config/`, etc.)
+12. Identify environment variables
+13. Find secrets patterns
+14. Check for feature flags
+
+### 1.5 Testing & CI/CD
+15. Detect test frameworks and patterns
+16. Map test directory structure
+17. Detect CI/CD pipelines
+18. Find deployment configurations
+
+### 1.6 Existing Documentation
+19. Check for README files
+20. Find API documentation (OpenAPI, Swagger)
+21. Locate architecture docs or diagrams
+
+**Output:** Comprehensive Codebase Report
+
+```markdown
+## Codebase Analysis
+
+### Tech Stack
+| Layer | Technology | Version | Confidence |
+|-------|------------|---------|------------|
+| Runtime | {detected} | {version} | High/Medium |
+| Framework | {detected} | {version} | High/Medium |
+| Database | {detected} | {version} | High/Medium |
+| Cache | {detected} | {version} | High/Medium |
+
+### Domains Detected
+| Domain | Source Folders | Entities | Endpoints | Confidence |
+|--------|----------------|----------|-----------|------------|
+| {domain} | {folders} | {count} | {count} | High/Medium/Low |
+{ALL domains listed}
+
+### Database Schema
+| Table/Model | Domain | Columns | Relationships | Confidence |
+|-------------|--------|---------|---------------|------------|
+{ALL tables/models listed}
+
+### API Endpoints
+| Method | Path | Domain | Auth | Confidence |
+|--------|------|--------|------|------------|
+{ALL endpoints listed}
+
+### Infrastructure
+- **Containerized:** {yes/no}
+- **CI/CD:** {platform}
+- **Deployment:** {method}
+- **Cloud:** {provider}
+
+### Existing Docs
+- **README:** {quality assessment}
+- **API docs:** {OpenAPI/Swagger/None}
+- **Architecture:** {found/not found}
+```
+
+---
+
+## Phase 2: Clarify
+
+**Goal:** Fill gaps that code analysis cannot determine
+
+**Actions:**
+1. Generate Gaps Report from scan
+2. Present structured questions
+3. Accept user inputs
+4. Mark confidence levels
+
+### Gaps Report
+
+```markdown
+## Gaps Identified
+
+Based on my scan, I need clarification on:
+
+### High Priority (Blocks Atlas Generation)
+
+| Area | What I Found | What I Need |
+|------|--------------|-------------|
+| Domain Boundaries | {detected domains} | Are these correct? Any to merge/split? |
+| Database | {tables found} | Is this complete? Any raw SQL? |
+| API Routes | {endpoints found} | Which are public vs internal? Deprecated? |
+
+### Medium Priority (Improves Accuracy)
+
+| Area | What I Found | What I Need |
+|------|--------------|-------------|
+| Tech Rationale | {stack detected} | Why these choices? |
+| External APIs | {integrations found} | What does each do? |
+| Auth Pattern | {auth detected} | External IdP or self-managed? |
+
+### Business Context (Cannot Infer from Code)
+
+| Area | What I Need |
+|------|-------------|
+| Product Vision | What is this system for? |
+| Users/Actors | Who uses this? |
+| Critical Flows | What are the key user journeys? |
+| Compliance | GDPR, PCI, HIPAA requirements? |
+```
+
+### Structured Questions
+
+```markdown
+## Questions
+
+### 1. Domain Boundaries
+
+I detected these domains from folder structure:
+
+| Domain | Folders | Entities | Confidence |
+|--------|---------|----------|------------|
+{ALL detected domains}
+
+**Questions:**
+- Are these domain boundaries correct?
+- Should any be merged or split?
+- Are there domains I missed?
+
+**Your input:** {free text}
+
+---
+
+### 2. Complete Database Schema
+
+I found:
+- {ORM}: {count} models
+- Migrations: {count} files
+
+**Questions:**
+- Is this the complete schema?
+- Any raw SQL not in ORM?
+- Which are core vs supporting entities?
+
+**Your input:** {free text}
+
+---
+
+### 3. API Completeness
+
+I detected {count} endpoints:
+
+| Method | Path | Confidence |
+|--------|------|------------|
+{sample endpoints}
+
+**Questions:**
+- Which are public-facing vs internal?
+- Any deprecated endpoints?
+- Webhooks or callbacks I missed?
+
+**Your input:** {free text}
+
+---
+
+### 4. Business Context
+
+Code cannot tell me:
+- What is this product for?
+- Who are the main users?
+- What are the critical business flows?
+- Any compliance requirements?
+
+**Your input:** {free text}
+
+---
+
+### 5. Screens/UI (if frontend exists)
+
+I detected {count} routes/pages:
+
+| Route | Component | Confidence |
+|-------|-----------|------------|
+{detected routes}
+
+**Questions:**
+- Are these all the screens?
+- Any screens behind feature flags?
+- Which are public vs authenticated?
+
+**Your input:** {free text}
+```
+
+### Confidence Update
+
+After clarification, update confidence:
+
+| Item | Before | After | Source |
+|------|--------|-------|--------|
+| Domain: auth | Inferred (High) | **Confirmed** | User verified |
+| Domain: payment | Inferred (Low) | **Confirmed** | User corrected |
+| Database schema | Inferred (Medium) | **Confirmed** | User provided context |
+| Business context | Unknown | **Confirmed** | User provided |
+
+**Human Gate:** Proceed when all high-priority gaps are resolved.
+
+---
+
+## Phase 3: Generate Complete Atlas
+
+**Goal:** Produce comprehensive Atlas from scan + clarifications (ALL domains at once)
+
+**Actions:**
+1. Create `.astraler-docs/` folder structure
+2. Generate complete `atlas/` folder
+3. Generate supporting files
+
+### Atlas Generation
+
+Generate ALL of these in one pass:
+
+#### `atlas/index.md`
+- Product vision (from clarification)
+- Complete tech stack (from scan)
+- ALL domains with purpose and priority
+- Domain relationship diagram
+- Project structure (from scan)
+- External integrations
+
+#### `atlas/database.md`
+- Complete ERD showing ALL entities (from scan)
+- ALL tables with columns, types, constraints
+- ALL relationships (detected + confirmed)
+- Indexes (from scan)
+- Cross-domain references
+- Confidence markers for inferred sections
+
+#### `atlas/screens.md` (if UI exists)
+- Navigation map showing ALL screens
+- ALL screens table (route, domain, auth)
+- Screen details (from scan + clarification)
+
+#### `atlas/api.md`
+- Base URL and authentication (from scan)
+- ALL endpoints summary (from scan)
+- Endpoint details (detected + confirmed)
+- Webhooks (if found)
+- Confidence markers for inferred sections
+
+#### `atlas/tasks.md`
+- Documentation completion tasks
+- Technical debt identified
+- Suggested improvements
+- Priority based on domain importance
+
+### Confidence Markers
+
+Mark sections with confidence:
+
+```markdown
+## Users Table
+
+> **Confidence:** Confirmed (from Prisma schema + user validation)
+
+| Column | Type | Constraints |
+|--------|------|-------------|
+| id | uuid | PK |
+| email | varchar | UK, NOT NULL |
+...
+```
+
+```markdown
+## Payment Flow
+
+> **Confidence:** Inferred (Medium) - based on code analysis, needs validation
+
+1. User initiates checkout
+2. Payment intent created via Stripe
+3. ...
+```
+
+---
+
+### Human Gate: Atlas Approval
+
+```markdown
+## Atlas Complete
+
+### Generated from Scan + Clarification
+
+| File | Content | Confidence |
+|------|---------|------------|
+| `atlas/index.md` | {X} domains, tech stack | Mixed |
+| `atlas/database.md` | {Y} tables, {Z} relationships | {breakdown} |
+| `atlas/screens.md` | {W} screens | {breakdown} |
+| `atlas/api.md` | {V} endpoints | {breakdown} |
+| `atlas/tasks.md` | {U} tasks | N/A |
+
+### Confidence Summary
+
+| Level | Count | Action Needed |
+|-------|-------|---------------|
+| Confirmed | {count} | None |
+| Inferred (High) | {count} | Light review |
+| Inferred (Medium) | {count} | Validate |
+| Inferred (Low) | {count} | Likely needs correction |
+
+### Sections Needing Review
+1. {section}: {reason}
+2. {section}: {reason}
+
+---
+**Approve Atlas?**
+[y] Yes, expand to full structure | [e] Edit specific file | [v] Validate low-confidence sections first
+```
+
+---
+
+## 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) |
+| `atlas/database.md` | `03-arch/data-schema.md` |
+| `atlas/database.md` (per domain) | `03-arch/domains/{domain}.arch.md` |
+| `atlas/screens.md` (per domain) | `02-spec/domains/{domain}.md` (screens) |
+| `atlas/api.md` (cross-domain) | `02-spec/core/flows.md` |
+| `atlas/api.md` (per domain) | `02-spec/domains/{domain}.md` (API) |
+| `atlas/tasks.md` | `04-tasks/milestones.md` |
+| `atlas/tasks.md` (per domain) | `04-tasks/domains/{domain}.tasks.md` |
+| Scan results | `context/constraints.md` |
+| Clarification | `context/assumptions.md` |
+| Code analysis | `context/glossary.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
+│   │   ├── flows.md
+│   │   └── rules.md
+│   └── domains/
+│       └── {domain}.md             # One per detected domain
+│
+├── 03-arch/                        # AUTO-GENERATED from Atlas
+│   ├── _index.md
+│   ├── overview.md
+│   ├── data-schema.md
+│   ├── standards.md                # From detected patterns
+│   ├── decisions.md                # Template + detected decisions
+│   └── domains/
+│       └── {domain}.arch.md        # One per detected domain
+│
+├── 04-tasks/                       # AUTO-GENERATED from Atlas
+│   ├── _index.md
+│   ├── milestones.md
+│   └── domains/
+│       └── {domain}.tasks.md       # One per detected domain
+│
+├── 05-changes/
+│   ├── _index.md
+│   ├── changelog.md
+│   └── impact/
+│
+├── context/
+│   ├── constraints.md              # From scan (tech constraints)
+│   ├── assumptions.md              # From clarification
+│   └── glossary.md                 # From code analysis
+│
+└── ai/
+    ├── guardrails.md               # Based on detected patterns
+    └── quality_gates.md            # Based on existing CI/CD
+```
+
+### Expansion Rules
+
+1. **Preserve confidence markers** in generated files
+2. **All generated files include proper headers** (status, version, owner)
+3. **All generated files include required Mermaid diagrams**
+4. **Files with low-confidence sections are marked `status: Draft`**
+5. **Atlas remains the source of truth**
+
+### Post-Expansion Summary
+
+```markdown
+## Expansion Complete
+
+### Files Generated
+| Folder | Files | Confidence |
+|--------|-------|------------|
+| 02-spec/core/ | 3 | {breakdown} |
+| 02-spec/domains/ | {N} | {breakdown} |
+| 03-arch/ | 4 | {breakdown} |
+| 03-arch/domains/ | {N} | {breakdown} |
+| 04-tasks/ | 1 | N/A |
+| 04-tasks/domains/ | {N} | N/A |
+| context/ | 3 | {breakdown} |
+| ai/ | 2 | {breakdown} |
+| **Total** | **{total}** | |
+
+### Low-Confidence Sections
+These sections need human validation:
+1. `03-arch/domains/payment.arch.md` — State machine inferred
+2. `02-spec/domains/order.md` — Business rules unclear
+
+### Ready to Build
+- Start with: `04-tasks/domains/{first-priority-domain}.tasks.md`
+- Validate: Low-confidence sections before implementation
+- 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/Approved based on confidence)
+3. **Low-confidence sections** = Need validation before implementation
+4. **Implementation** = Start from `04-tasks/`
+5. **Changes** = Modify Atlas first, re-expand affected sections
+
+---
+
+## Quick Reference
+
+```
+/astra:start --scan
+       │
+       ▼
+[1. Scan] ─────► Analyze entire codebase
+       │
+       ▼
+[2. Clarify] ──► Fill gaps (domains, schema, business)
+       │
+       ◆ Human provides context
+       │
+       ▼
+[3. Generate Atlas] ──► Complete atlas (ALL domains)
+       │
+       ◆ Human Approves
+       │
+       ▼
+[4. Auto-Expand] ──► Full Astraler Docs structure
+       │
+       ▼
+[Ready to Build]
+```
+
+---
+
+## Checklist
+
+### Phase 1: Scan Complete
+- [ ] Directory structure mapped
+- [ ] Tech stack identified
+- [ ] ALL domains detected
+- [ ] ALL database tables found
+- [ ] ALL endpoints detected
+- [ ] CI/CD analyzed
+
+### Phase 2: Clarification Complete
+- [ ] Domain boundaries confirmed
+- [ ] Database schema validated
+- [ ] API completeness verified
+- [ ] Business context provided
+- [ ] High-priority gaps resolved
+
+### Phase 3: Atlas Complete
+- [ ] `atlas/index.md` — All domains, tech stack
+- [ ] `atlas/database.md` — All entities, relationships
+- [ ] `atlas/screens.md` — All screens (if UI)
+- [ ] `atlas/api.md` — All endpoints
+- [ ] `atlas/tasks.md` — Documentation + improvement tasks
+
+### Phase 4: Expansion Complete
+- [ ] `02-spec/` — Core + all domain specs
+- [ ] `03-arch/` — Overview + all domain arch
+- [ ] `04-tasks/` — Milestones + all domain tasks
+- [ ] `context/` — Constraints, assumptions, glossary
+- [ ] `ai/` — Guardrails, quality gates
+- [ ] All files have proper headers
+- [ ] Low-confidence sections marked
+
+---
+
+## Confidence Levels
+
+| Level | Meaning | Source | Action |
+|-------|---------|--------|--------|
+| **Confirmed** | User verified | Clarification | Trust |
+| **Inferred (High)** | Strong code signals | Scan | Light review |
+| **Inferred (Medium)** | Unclear signals | Scan | Validate |
+| **Inferred (Low)** | Educated guess | Scan | Likely needs correction |
+
+---
+
+## Limitations
+
+- Cannot infer business intent from code alone
+- May miss undocumented business rules
+- Confidence varies by code quality/naming
+- Always requires human validation for low-confidence sections
+- Clarification phase reduces but doesn't eliminate guesswork