astragentic 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# Astragentic Installer
+
+This is the installer for the Astragentic DevKit. It sets up the necessary configuration and resources for the Astraler framework.
+
+## Installation
+
+Run the following command in your project root:
+
+```bash
+npx astragentic install
+```
+
+This command will:
+1.  Install `.claude` configuration to your project root.
+2.  Install `_astraler` resources to your project root.
+
+## Development & Deployment
+
+### Manual Publishing (Locally)
+
+When publishing manually from your local machine, **you do not need to manually configure a token file**. Authenticity is handled by your local npm session.
+
+1.  **Login to npm**:
+    Open your terminal and run:
+    ```bash
+    npm login
+    ```
+    Follow the browser prompts to authenticate. Once done, your machine is authorized.
+
+2.  **Ship It**:
+    We provide a `ship.sh` script in the root of the repository to automate the bundling and publishing process.
+
+    ```bash
+    # From the repository root
+    ./scripts/ship.sh <version>
+    
+    # Example:
+    ./scripts/ship.sh 0.0.1
+    ```
+
+    The script will:
+    - Update the version in `package.json`.
+    - Bundle the latest `devkit/claude-code` and `_astraler` content.
+    - Ask for confirmation before running `npm publish`.
+
+### Automated Publishing (CI/CD)
+
+For CI/CD (like GitHub Actions), we use an automation token.
+- Variable: `NPM_TOKEN`
+- Location: set in GitHub Repository Secrets.
+
+This is NOT required for manual local deployment.

package/assets/_astraler/engine.md

@@ -0,0 +1,307 @@
+# Astra Engine
+
+> Single source of truth for Astra execution rules.
+
+---
+
+## Core Principles
+
+1. **Artifact-first**: All work reads/writes `.astraler-docs/`
+2. **Human-gated**: AI drafts, human approves status changes
+3. **Change-tracked**: Approved docs need CHG record before edit
+4. **Scope-bound**: Never expand beyond current domain/task
+5. **Cognitive sync**: Validate understanding before proceeding
+
+---
+
+## Command Reference
+
+### Discovery & Status
+
+| Command | Purpose | Read-Only |
+|---------|---------|-----------|
+| `/astra:start` | Bootstrap or scan project | No |
+| `/astra:status` | Show project state | Yes |
+| `/astra:help` | List commands, workflow | Yes |
+
+### Design Phase
+
+| Command | Purpose | Checkpoints |
+|---------|---------|-------------|
+| `/astra:spec <domain>` | Create domain specification | Yes (per section) |
+| `/astra:arch <domain>` | Create domain architecture | Yes (per section) |
+| `/astra:plan <domain>` | Generate tasks | No |
+
+### Build Phase
+
+| Command | Purpose | Flags |
+|---------|---------|-------|
+| `/astra:build <target>` | Implement tasks | `--auto` for batch |
+| `/astra:verify` | Validate consistency | `--all` for all domains |
+
+### Governance
+
+| Command | Purpose | Creates |
+|---------|---------|---------|
+| `/astra:change <title>` | Modify approved docs | CHG record |
+
+---
+
+## Document Lifecycle
+
+```
+Draft → Approved → Deprecated
+  │         │
+  │         └── Requires CHG to edit
+  └── AI may edit freely
+```
+
+**Status rules:**
+- `Draft`: Work in progress, editable
+- `Approved`: Human-reviewed, locked without CHG
+- `Deprecated`: Archived, read-only
+
+---
+
+## Human Gates
+
+**STOP and WAIT for human input:**
+- Before status transition (Draft → Approved)
+- Before deployment/commit
+- Before cross-domain changes
+- When CHG is required
+
+**Auto-proceed with reporting:**
+- Consistency checks
+- Test coverage metrics
+- Lint/format results
+
+---
+
+## ID Conventions
+
+| Type | Format | Example |
+|------|--------|---------|
+| Task | `TSK-{domain}-{###}` | `TSK-order-001` |
+| Change | `CHG-{YYYY-MM-DD}-{slug}` | `CHG-2026-01-04-add-refund` |
+| ADR | `ADR-{YYYY-MM-DD}-{topic}` | `ADR-2026-01-04-use-redis` |
+
+---
+
+## Workflow Selection
+
+| Signal | Workflow | Entry |
+|--------|----------|-------|
+| No `.astraler-docs/` | Greenfield | `/astra:start` |
+| Has `.astraler-docs/`, no spec | Greenfield | `/astra:start` |
+| Has codebase, no docs | Brownfield | `/astra:start --scan` |
+| New requirement on existing | Change | `/astra:change` |
+
+---
+
+## Output Structure (FINAL)
+
+```
+.astraler-docs/
+├── _index.md
+├── 01-context/
+│   ├── _index.md
+│   ├── product.md              # Vision, priorities, anti-goals
+│   ├── constraints.md          # Technical & business constraints
+│   ├── assumptions.md          # Validatable assumptions
+│   └── glossary.md             # Domain terminology
+│
+├── 02-spec/
+│   ├── _index.md
+│   ├── core/
+│   │   ├── overview.md         # System scope, actors
+│   │   ├── flows.md            # Cross-domain flows
+│   │   └── rules.md            # Global business rules
+│   └── domains/
+│       └── {domain}.md         # Per-domain specification
+│
+├── 03-arch/
+│   ├── _index.md               # Navigation only
+│   ├── overview.md             # System architecture, tech stack
+│   ├── data-schema.md          # Global database schema
+│   ├── decisions.md            # ADR collection
+│   ├── standards.md            # Engineering standards, DoD
+│   └── domains/
+│       └── {domain}.arch.md    # Per-domain architecture
+│
+├── 04-tasks/
+│   ├── _index.md
+│   ├── milestones.md           # Epic-level goals
+│   ├── domains/
+│   │   └── {domain}.tasks.md   # Per-domain task breakdown
+│   └── sprints/                # Optional time-box view
+│       └── {sprint}.md
+│
+├── 05-changes/
+│   ├── _index.md
+│   ├── changelog.md            # Change history summary
+│   └── impact/
+│       └── CHG-YYYY-MM-DD-*.md # Individual change records
+│
+└── ai/
+    ├── guardrails.md           # AI agent constraints
+    └── quality_gates.md        # Test taxonomy & gates
+```
+
+---
+
+## Mermaid Diagram Requirements
+
+All generated documentation MUST include visual diagrams:
+
+| Document Type | Required Diagrams |
+|---------------|-------------------|
+| **Spec** (`02-spec/domains/*.md`) | `sequenceDiagram`, `stateDiagram-v2`, `erDiagram` |
+| **Arch** (`03-arch/domains/*.arch.md`) | `flowchart`, `classDiagram`, `sequenceDiagram`, `erDiagram`, `stateDiagram-v2` |
+| **Tasks** (`04-tasks/domains/*.tasks.md`) | `pie` (status distribution), `flowchart` (dependency graph) |
+| **CHG** (`05-changes/impact/CHG-*.md`) | `flowchart` (impact analysis) |
+
+**Diagram Update Rules:**
+- When task status changes → update `pie` counts and `flowchart` node styles
+- When adding CHG → include impact flowchart with affected artifacts
+- Verify passes only when all required diagrams are present
+
+---
+
+## Quality Checks
+
+Before writing spec:
+- `01-context/product.md` exists
+
+Before writing arch:
+- `02-spec/domains/{domain}.md` exists (Draft+)
+
+Before writing tasks:
+- Spec + arch exist for domain
+
+Before implementing:
+- Task has spec ref, arch ref, testable AC
+
+Before approving:
+- Human has reviewed
+- `/astra:verify` passes
+- All required Mermaid diagrams present
+
+---
+
+## Quality Gates by Change Type
+
+| Change Type | Required |
+|-------------|----------|
+| API change | Contract test + integration test |
+| Data change | Migration + rollback + test |
+| Payment/refund | Idempotency + negative cases + audit |
+| Auth | Security baseline + rate limiting |
+
+---
+
+## Versioning
+
+| Change Type | Version Bump |
+|-------------|--------------|
+| Wording only | Patch (v1.0 → v1.1) |
+| New flow/rule | Minor (v1.1 → v2.0) |
+| Contract/boundary | Major (v2.0 → v3.0) |
+
+---
+
+## Refactor Rules
+
+| Level | Scope | Allowed |
+|-------|-------|---------|
+| A | Internal only | Yes, inline |
+| B | Contract/boundary | Requires CHG |
+| C | Cross-domain | Requires CHG + ADR |
+
+---
+
+## Checkpoint Pattern
+
+Commands with checkpoint pattern save progress after each section:
+
+```
+Generate Section → Save to File → Present for Review → [c/e/q] → Next Section
+```
+
+**Checkpoint controls:**
+- `[c]` Continue to next section
+- `[e]` Edit current section
+- `[q]` Quit (progress saved)
+
+Commands using checkpoints:
+- `/astra:spec` — saves after Purpose, Flows, Rules, Data, Criteria
+- `/astra:arch` — saves after Overview, Components, Contracts, Data, State
+
+This prevents work loss and enables iterative refinement.
+
+---
+
+## Interactive Diagram Review
+
+For required Mermaid diagrams, present each for validation:
+
+```markdown
+## {Diagram Type}: {Subject}
+
+```mermaid
+{diagram content}
+```
+
+**Does this accurately represent {the flow/architecture/data}?**
+[y] Yes, continue | [e] Edit | [s] Skip (flags in verify)
+```
+
+Diagrams skipped during creation are flagged as warnings by `/astra:verify`.
+
+---
+
+## Cognitive Sync Checkpoint
+
+Before major phase transitions, present understanding for explicit validation:
+
+**Used in:**
+- Greenfield Phase 2 → Phase 3 (Brainstorm → Distill)
+
+**Format:**
+```markdown
+## My Understanding
+
+### What We're Building
+{summary}
+
+### Key Actors
+{list}
+
+### Core Flows
+{list}
+
+### Anti-goals
+{list}
+
+### Assumptions
+{table with risk levels}
+
+---
+**Is this correct?** [y] Yes | [n] No | [p] Partially
+```
+
+This ensures human and AI are aligned before committing to documentation.
+
+---
+
+## Execution Modes
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| Interactive | (default) | Confirm gates, pause on errors |
+| Auto | `--auto` | Skip confirmations, continue on non-critical errors |
+
+**Auto mode will NOT skip:**
+- Missing prerequisites (spec, arch)
+- Level-B/C refactors (require CHG)
+- Critical validation failures