astragentic 1.0.0 → 1.5.0

package/README.md

@@ -6,8 +6,17 @@ This is the installer for the Astragentic DevKit. It sets up the necessary confi
 
 Run the following command in your project root:
 
+### Default (Latest)
 ```bash
 npx astragentic install
+# OR explicitly:
+npx astragentic@latest install
+```
+
+### Specific Version
+If you need to install a specific version (e.g., to downgrade or ensure consistency):
+```bash
+npx astragentic@1.0.0 install
 ```
 
 This command will:

package/assets/_astraler/workflows/greenfield.md

@@ -144,19 +144,17 @@ Validate complete understanding before generation:
 
 ### Atlas Folder Structure
 
+**Reading Order:** Files are numbered 1→5 for sequential reading.
+
 ```
 .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
+├── atlas/                          # PRIMARY - read in order 1→5
+│   ├── 1-overview.md              # High-level vision, goals, domains (start here)
+│   ├── 2-context.md               # Constraints, assumptions, glossary
+│   ├── 3-database.md              # Complete schema, ALL entities
+│   ├── 4-screens.md               # UI inventory (if UI exists)
+│   └── 5-api.md                   # API surface inventory (not detailed contracts)
 ├── changes/
 │   ├── changelog.md
 │   └── impact/
@@ -167,39 +165,43 @@ Validate complete understanding before generation:
 
 ### 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)
+#### `1-overview.md` — High-Level Overview (Start Here)
+- Project vision (1-2 sentences)
+- Success metrics (table)
+- Tech stack summary (table)
+- ALL domains listed with purpose and priority
+- Domain relationship diagram (Mermaid flowchart)
 - Project structure (folder tree)
-- External integrations
 
-#### `atlas/database.md`
-- Complete ERD (Mermaid) showing ALL entities
+**Simplicity:** Keep high-level; detailed domain specs go in `domains/` if needed.
+
+#### `2-context.md` — Background & Constraints
+- Key constraints (technical, business, timeline)
+- Assumptions and risks
+- Glossary of domain terms
+
+**Simplicity:** Consolidates what was previously a separate `context/` folder.
+
+#### `3-database.md` — Data Model
+- Complete ERD (Mermaid erDiagram)
 - 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
+- Migration strategy (if applicable)
+
+#### `4-screens.md` — UI Inventory (If UI Exists)
+- Navigation map (Mermaid flowchart)
+- ALL screens table (route, domain, auth requirement)
+- Brief screen purpose (1 line each)
+
+**Simplicity:** No detailed component breakdowns; just inventory.
+
+#### `5-api.md` — API Surface Inventory
+- Base URL and authentication method
+- ALL endpoints summary table (method, route, domain, auth)
+- Estimated endpoint count per domain
+- External integrations (Stripe, SendGrid, etc.)
+
+**Simplicity:** Sketch the API surface only. No request/response schemas yet — those come during `/astra:plan` or implementation.
 
 ---
 
@@ -210,17 +212,17 @@ 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
+### Generated Files (read in order 1→5)
+- `atlas/1-overview.md` — {X} domains, tech stack, vision
+- `atlas/2-context.md` — constraints, assumptions, glossary
+- `atlas/3-database.md` — {Y} tables, {Z} relationships
+- `atlas/4-screens.md` — {W} screens across all domains
+- `atlas/5-api.md` — ~{V} endpoints (surface inventory)
 
 ### Domains Covered
-| Domain | Entities | Screens | Endpoints | Tasks |
-|--------|----------|---------|-----------|-------|
-| {domain} | {count} | {count} | {count} | {count} |
+| Domain | Priority | Entities | Screens | Endpoints |
+|--------|----------|----------|---------|-----------|
+| {domain} | P0/P1 | {count} | {count} | ~{count} |
 {ALL domains listed}
 
 ### Ready to Expand
@@ -247,36 +249,35 @@ Upon approval, will auto-generate:
 
 | 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` |
+| `atlas/1-overview.md` | `02-spec/core/overview.md` |
+| `atlas/1-overview.md` | `03-arch/overview.md` |
+| `atlas/1-overview.md` (domains) | `02-spec/domains/{domain}.md` (overview section) |
+| `atlas/2-context.md` | Constraints/assumptions embedded in specs |
+| `atlas/3-database.md` | `03-arch/data-schema.md` |
+| `atlas/3-database.md` (per domain) | `03-arch/domains/{domain}.arch.md` (data models) |
+| `atlas/4-screens.md` (per domain) | `02-spec/domains/{domain}.md` (screens section) |
+| `atlas/5-api.md` (cross-domain) | `02-spec/core/flows.md` |
+| `atlas/5-api.md` (per domain) | `02-spec/domains/{domain}.md` (API section) |
+| `atlas/5-api.md` (per domain) | `03-arch/domains/{domain}.arch.md` (contracts) |
 
 ### Generated Structure
 
 ```
 .astraler-docs/
 ├── _index.md
-├── atlas/                          # SOURCE (human-approved)
-│   ├── index.md
-│   ├── database.md
-│   ├── screens.md
-│   ├── api.md
-│   └── tasks.md
+├── atlas/                          # SOURCE (human-approved, read 1→5)
+│   ├── 1-overview.md
+│   ├── 2-context.md
+│   ├── 3-database.md
+│   ├── 4-screens.md
+│   └── 5-api.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)
+│   │   ├── overview.md            # ← from atlas/1-overview.md
+│   │   ├── flows.md               # ← from atlas/5-api.md (cross-domain)
+│   │   └── rules.md               # ← from atlas/5-api.md (validation)
 │   └── domains/
 │       ├── auth.md                # ← from atlas (auth sections)
 │       ├── catalog.md             # ← from atlas (catalog sections)
@@ -285,8 +286,8 @@ Upon approval, will auto-generate:
 │
 ├── 03-arch/                        # AUTO-GENERATED from Atlas
 │   ├── _index.md
-│   ├── overview.md                # ← from atlas/index.md
-│   ├── data-schema.md             # ← from atlas/database.md
+│   ├── overview.md                # ← from atlas/1-overview.md
+│   ├── data-schema.md             # ← from atlas/3-database.md
 │   ├── standards.md               # ← generated (DoD, conventions)
 │   ├── decisions.md               # ← generated (ADR template)
 │   └── domains/
@@ -295,25 +296,11 @@ Upon approval, will auto-generate:
 │       ├── 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
@@ -400,16 +387,15 @@ After expansion:
 - [ ] 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
+### Atlas Files Complete (read in order)
+- [ ] `atlas/1-overview.md` — Vision, domains, tech stack
+- [ ] `atlas/2-context.md` — Constraints, assumptions, glossary
+- [ ] `atlas/3-database.md` — All entities, relationships
+- [ ] `atlas/4-screens.md` — All screens, navigation
+- [ ] `atlas/5-api.md` — API surface inventory (~count per domain)
 
 ### 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

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

@@ -10,128 +10,55 @@ This file provides guidance to Claude Code when working with this repository.
 
 ---
 
-## Framework Architecture
+## Start Here
 
-Astragentic operates through three interconnected roots:
+**New to this project? Read the Atlas first:**
 
-| 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 |
+→ [`.astraler-docs/atlas/index.md`](.astraler-docs/atlas/index.md)
 
-```
-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
-```
+The Atlas contains the complete project blueprint: vision, tech stack, database schema, screens, API contracts, and implementation tasks.
 
 ---
 
-## 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
+## Documentation
 
-### 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
+All project documentation lives in `.astraler-docs/`:
 
-### 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
+| Document | What It Contains |
+|----------|-----------------|
+| [`atlas/`](.astraler-docs/atlas/) | **Complete project blueprint** (start here) |
+| [`context/`](.astraler-docs/context/) | Constraints, assumptions, glossary |
+| [`domains/`](.astraler-docs/domains/) | Deep-dives for complex domains (optional) |
+| [`changes/`](.astraler-docs/changes/) | Change history and impact records |
+| [`ai/`](.astraler-docs/ai/) | AI guardrails and quality gates |
 
-### 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
+See [`.astraler-docs/_index.md`](.astraler-docs/_index.md) for full navigation.
 
 ---
 
 ## 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:status` | Show current state and suggest next action |
 | `/astra:change <title>` | Manage changes to approved docs |
+| `/astra:help` | List available commands |
 
 ---
 
 ## 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]
+1. Read [`atlas/index.md`](.astraler-docs/atlas/index.md) for project overview
+2. Check [`atlas/database.md`](.astraler-docs/atlas/database.md) for data models
+3. Review [`atlas/api.md`](.astraler-docs/atlas/api.md) for API contracts
+4. See [`ai/guardrails.md`](.astraler-docs/ai/guardrails.md) for AI 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]
+### Critical Rules
+- Never edit `Approved` docs without a Change Record (CHG)
+- Atlas is the source of truth — changes flow Atlas → expanded docs
+- [CUSTOMIZE: Add project-specific forbidden patterns]
 
 ---
 
@@ -160,26 +87,6 @@ All project documentation lives in `.astraler-docs/`. Read these before making c
 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
+3. Changes propagate: Atlas → expanded docs → code
 
-- **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)
+See [`changes/changelog.md`](.astraler-docs/changes/changelog.md) for history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astragentic",
-  "version": "1.0.0",
+  "version": "1.5.0",
   "description": "Installer for Astragentic devkit",
   "bin": {
     "astragentic": "./bin/cli.js"