guardian-framework 0.1.0

package/templates/pi/context/domain-workflow.md

@@ -0,0 +1,180 @@
+# Domain-Driven Design Workflow (End-to-End)
+
+## Overview
+
+The full workflow from business idea to implemented architecture using Guardian's domain tools.
+Every step produces artifacts the next step consumes.
+
+```
+/domain --explore "business intent"
+    ↓  (agent fills exploration.md + ubiquitous-language.md automatically)
+/domain --architect-scaffold <session-id>
+    ↓  (generates modules, ADR-001, system-context.md)
+guardian project create --lang <lang>   (Epic 0 — greenfield only)
+    ↓
+/epic-plan --module <module-name>   (per-module planning)
+    ↓
+/implement-series
+```
+
+---
+
+## Step 1: Explore the Domain
+
+```bash
+/domain --explore "Describe your business domain here..."
+```
+
+**What happens:**
+- Creates a session ID and session file in `.pi/domain/exploration/<session-id>.md`
+- Writes `.pi/domain/exploration.md` with business context and empty table sections
+- Writes `.pi/domain/ubiquitous-language.md` (initial glossary)
+- **Injects the DDD analysis prompt as a new conversation turn** via `pi.sendMessage()` with `triggerTurn=true`
+
+**The agent automatically:**
+- Analyzes the business context using DDD
+- Identifies actors, roles, functional/non-functional requirements, assumptions
+- Maps bounded contexts with entities, value objects, and aggregate roots
+- Defines domain events and their triggers
+- Builds the ubiquitous language glossary
+- **Fills in all empty tables** in `.pi/domain/exploration.md`
+- **Updates** `.pi/domain/ubiquitous-language.md` with glossary terms
+
+**Output files:**
+| File | Contents |
+|------|----------|
+| `.pi/domain/exploration.md` | Full analysis with all sections populated |
+| `.pi/domain/ubiquitous-language.md` | Canonical glossary with terms |
+| `.pi/domain/exploration/<session-id>.md` | Session record with synced analysis |
+
+---
+
+## Step 2: Scaffold Architecture
+
+```bash
+/domain --architect-scaffold <session-id>
+```
+
+**What happens:**
+- Reads the agent-filled `exploration.md` and syncs analysis into the session file
+- Calls `guardian-framework domain scaffold` to generate one module doc per bounded context
+- Generates ADR-001 (architecture pattern decision) with the bounded context list
+- Generates `system-context.md` with a mermaid diagram of bounded context flow
+- **Sends results as a follow-up message** so the agent sees what was generated
+
+**Agent responsibilities after scaffold:**
+- Generate additional ADRs — only `ADR-001` is created; the agent must create the rest
+- Fill in `## ADRs` sections in each module doc (initially `None yet`)
+- Fill in `## Key Files` sections in each module doc (initially `None yet`)
+- Update the CHANGELOG (initially a placeholder)
+
+**Output files:**
+| Path | Contents |
+|------|----------|
+| `.pi/architecture/modules/<context>.md` | One module doc per bounded context |
+| `.pi/architecture/decisions/ADR-001.md` | Architecture pattern decision |
+| `.pi/architecture/diagrams/system-context.md` | Mermaid bounded context flow |
+
+---
+
+## Step 3: Review & Validate (Optional)
+
+```bash
+/domain --validate <session-id>
+```
+
+Checks session file structure: bounded contexts, entities, ubiquitous language sections.
+
+---
+
+## Step 4: Plan Implementation
+
+Two approaches:
+
+**A) Project-wide overview:**
+```bash
+/epic-plan --overview
+```
+
+**B) Per-module planning (after Epic 0 scaffold):**
+```bash
+/epic-plan --module <module-name>
+```
+
+**Epic structure (4 layers):**
+1. **Contract Freeze** — define interfaces before implementation
+2. **Implementation Issues** — one per component
+3. **Proofing** — deterministic validation scripts + CI integration
+4. **Architecture Readiness** — runbook, DR, docs, observability, CI enforcement
+
+---
+
+## Step 5: Scaffold Project (Epic 0 — Greenfield Only)
+
+For a new project AFTER architecture is defined:
+
+```bash
+guardian project create --lang <language> --buildTool <maven|gradle>
+```
+
+Reads architecture modules and generates:
+- Source directories per module + Clean Architecture layers (domain/application/infrastructure/interfaces)
+- Build configuration (pom.xml / build.gradle / package.json)
+- CI pipeline (GitHub Actions or GitLab CI)
+- Stage scripts for the hardening pipeline
+
+Existing projects skip this step (detects existing `src/`).
+
+---
+
+## Step 6: Implement
+
+```bash
+/implement-series
+# or follow the pipeline generated by /architect
+```
+
+Each issue follows the contract freeze → implementation → proofing → readiness sequence.
+
+---
+
+## Agent Definitions
+
+Canonical agent definitions in `.pi/agents/` using 6-section format (Purpose, Authority, Inputs, Outputs, DoD, Escalation):
+
+| Agent | Role | Phase |
+|-------|------|-------|
+| Architecture Coordinator | Coordinator | A — Planning |
+| Issue Factory | Coordinator | B — Issue Generation |
+| Bootstrap Implementer | Builder | C — Implementation |
+| Architecture Validator | Validator | D — Validation |
+| Security Validator | Validator | D — Validation |
+| Operations Validator | Validator | D — Validation |
+
+## 4-Phase Delivery Pipeline
+
+```
+Phase A: Planning       → .pi/agents/architecture-coordinator.md
+Phase B: Issue Gen      → .pi/agents/issue-factory.md
+Phase C: Implement      → .pi/agents/bootstrap-implementer.md
+Phase D: Validation     → .pi/agents/architecture-validator.md + security + operations
+```
+
+Each phase produces a validated artifact before the next begins.
+
+## Deterministic Validation Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/ci/check_planning_packet.py` | Validates planning packet before issue generation |
+| `scripts/ci/validate_agent_output.py` | Validates agent output schema per role |
+| `scripts/ci/run_preflight.sh` | Orchestrates local CI checks |
+
+## How It Works: sendMessage Pattern
+
+All commands that need the agent to continue working use `pi.sendMessage()` with `triggerTurn=true` instead of returning text. This injects the message as a new user conversation turn, which the agent processes naturally — writing files, calling tools, and continuing the workflow.
+
+Commands using this pattern:
+- `/domain --explore` — sends DDD analysis prompt
+- `/domain --architect-scaffold` — sends scaffold results
+- `/domain --validate` — sends validation results

package/templates/pi/context/output-formats.md

@@ -0,0 +1,135 @@
+# Output Formats
+
+> **Purpose:** Standardized report templates. All validators use these. Referenced, not duplicated.
+> **Generic:** Adjust severity levels and fields to your project.
+
+---
+
+## Validation Report (All Validators)
+
+```markdown
+## [Validator Name] Report
+
+**Task:** [task-id or description]
+**Scope:** [Simple/Moderate/Complex/Critical]
+**Files Reviewed:** [list]
+
+### Results
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| [Check 1] | ✅/❌ | [notes] |
+| [Check 2] | ✅/❌ | [notes] |
+
+### Issues
+
+| Severity | File:Line | Description | Fix |
+|----------|-----------|-------------|-----|
+| [Critical/High/Medium/Low] | [file:line] | [description] | [fix] |
+
+### Verdict
+
+- [ ] APPROVED
+- [ ] APPROVED WITH CONDITIONS
+- [ ] REQUIRES CHANGES
+- [ ] REJECTED
+
+### Conditions (if any)
+- [condition 1]
+```
+
+## Design Proposal
+
+```markdown
+## Design Proposal: [Name]
+
+### Summary
+[1-2 paragraphs]
+
+### Approach
+[Detailed approach]
+
+### Affected Components
+- [Component]: [Changes]
+
+### Tradeoffs
+| Option | Pros | Cons | Decision |
+|--------|------|------|----------|
+| A | ... | ... | Chosen |
+| B | ... | ... | Rejected |
+
+### Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Risk] | [H/M/L] | [H/M/L] | [Mitigation] |
+```
+
+## Implementation Plan
+
+```markdown
+## Implementation Plan: [Name]
+
+### Scope
+- **Files:** [count]
+- **Estimated lines:** [count]
+- **Complexity:** [Simple/Moderate/Complex/Critical]
+
+### Steps
+1. [Step 1] — [file(s)]
+2. [Step 2] — [file(s)]
+3. [Step 3] — [file(s)]
+
+### Dependencies
+- [Dependency 1]
+- [Dependency 2]
+
+### Validation Contract
+> Items pre-validated at plan time. Post-code review checks ONLY wiring + build.
+- [ ] Architecture: [approved]
+- [ ] Security: [approved]
+- [ ] Operations: [approved]
+```
+
+## Epic Draft
+
+```markdown
+## Epic: [Name]
+
+### Goal
+[One sentence]
+
+### Issues
+- [ ] #[issue] — [title]
+- [ ] #[issue] — [title]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+### Validation
+- [ ] All issues merged
+- [ ] All CI green
+- [ ] Post-merge validation passed
+```
+
+## CI/MR Report
+
+```markdown
+## CI/MR Validation
+
+**PR:** #[number]
+**Branch:** [branch-name]
+
+### CI Status
+| Check | Status | Duration |
+|-------|--------|----------|
+| Build | ✅/❌ | [time] |
+| Test | ✅/❌ | [time] |
+| Lint | ✅/❌ | [time] |
+| Security | ✅/❌ | [time] |
+
+### Verdict
+- [ ] READY TO MERGE
+- [ ] NEEDS CHANGES
+- [ ] BLOCKED
+```

package/templates/pi/context/patterns-base.md

@@ -0,0 +1,47 @@
+# Code Patterns
+
+> **Purpose:** Reusable code templates and patterns. Referenced by agents, not duplicated.
+> **Generic:** Replace with your language/framework patterns.
+
+## Error Handling
+
+```[language]
+// [Pattern description]
+```
+
+## Tracing / Logging
+
+```[language]
+// [Pattern description]
+```
+
+## Cancellation / Cleanup
+
+```[language]
+// [Pattern description]
+```
+
+## Atomic Writes
+
+```[language]
+// [Pattern description]
+```
+
+## Data Structures
+
+```[language]
+// [Pattern description]
+```
+
+## Testing
+
+```[language]
+// [Pattern description]
+```
+
+## Anti-Patterns (NEVER DO)
+
+```[language]
+// ❌ [Bad pattern]
+// ✅ [Good pattern]
+```

package/templates/pi/context/patterns.md

@@ -0,0 +1,38 @@
+# Code Patterns
+
+> Code templates for reference. Agents read this to match patterns.
+> **Language-specific patterns** are in `.pi/languages/{{LANGUAGE}}-patterns.md`.
+
+## Error Handling
+
+{{ERROR_HANDLING_SECTION}}
+
+**Rule:** {{ERROR_HANDLING_RULE}}
+
+## Tracing
+
+{{TRACING_SECTION}}
+
+**Rule:** {{TRACING_RULE}}
+
+## Cancellation
+
+{{CANCELLATION_SECTION}}
+
+**Rule:** {{CANCELLATION_RULE}}
+
+## Atomic Writes
+
+{{ATOMIC_WRITE_SECTION}}
+
+**Rule:** {{ATOMIC_WRITE_RULE}}
+
+## Retry Logic
+
+```{{LANGUAGE}}
+// Exponential backoff: base_delay * 2^retry
+// Jitter: ±25% to prevent thundering herd
+// Max retries: 3
+```
+
+**Rule:** Max 3 retries. Exponential backoff with jitter.

package/templates/pi/context/project.md

@@ -0,0 +1,88 @@
+# Project Context
+
+> Single source of truth for project-specific knowledge. All agents load this ONCE.
+> **This is a template** — replace placeholders with actual values during `guardian init`.
+
+## Project Overview
+
+- **Name:** {{PROJECT_NAME}}
+- **Version:** {{PROJECT_VERSION}}
+- **Language:** {{LANGUAGE}}
+- **Type:** {{PROJECT_TYPE}}
+- **Repository:** {{REPOSITORY}}
+
+## Core Principles
+
+1. **Template-driven** - Workflows in templates, not dynamic generation
+2. **DAG-based** - Task nodes with dependencies, topological execution
+3. **Minimal LLM** - LLM = planning tool only
+4. **Bounded autonomy** - Hard caps on dynamic behavior
+5. **Bounded retries** - Max 3 retries with exponential backoff + jitter (±25%)
+6. **Risk-gated** - Safe=auto, Medium=confirm, Dangerous=dry-run
+7. **Pre-validated** - Validator catches errors BEFORE execution
+8. **Auditable** - Planning decisions tracked and diffable
+
+## Architecture
+
+### Structure
+
+```
+{{PROJECT_NAME}}/
+├── src/                 # Source code
+├── tests/               # Test files
+├── docs/                # Documentation
+└── .pi/                 # Agent framework
+```
+
+### Key Patterns
+
+- **Error handling:** {{ERROR_HANDLING_PATTERN}}
+- **Tracing:** {{TRACING_PATTERN}}
+- **Cancellation:** {{CANCELLATION_PATTERN}}
+- **Atomic writes:** {{ATOMIC_WRITE_PATTERN}}
+
+## Quality Gates
+
+### Before Commit
+```bash
+{{BUILD_COMMAND}} && {{FORMAT_COMMAND}}
+```
+
+### Before Push
+```bash
+{{TEST_COMMAND}} && {{LINT_COMMAND}}
+```
+
+### Before Merge
+```bash
+{{TEST_COMMAND}}
+{{LINT_COMMAND}}
+{{FORMAT_CHECK_COMMAND}}
+{{SECURITY_AUDIT_COMMAND}}
+```
+
+## Scope Classification
+
+| Scope | Files | Lines | Required Validators |
+|-------|-------|-------|---------------------|
+| Simple | 1 | < 50 | ci-mr (automated) |
+| Moderate | 2-5 | 50-200 | architecture-validator |
+| Complex | 5-15 | 200-500 | architecture + security |
+| Critical | 15+ or core | 500+ | All validators + human |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| docs/ARCHITECTURE.md | Architecture specification |
+| {{KEY_FILE_1}} | {{KEY_FILE_1_PURPOSE}} |
+| {{KEY_FILE_2}} | {{KEY_FILE_2_PURPOSE}} |
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `{{BUILD_COMMAND}}` | Build project |
+| `{{TEST_COMMAND}}` | Run tests |
+| `{{LINT_COMMAND}}` | Lint check |
+| `{{SECURITY_AUDIT_COMMAND}}` | Security audit |

package/templates/pi/domain/exploration.md

@@ -0,0 +1,93 @@
+---
+session_id: {{SESSION_ID}}
+created: {{CREATED_DATE}}
+business_context: "{{BUSINESS_CONTEXT}}"
+status: {{STATUS}}
+---
+
+# Domain Exploration: {{SESSION_ID}}
+
+> Automatically generated by `guardian domain explore`.
+> Status: **{{STATUS}}** — *draft* = AI-suggested, *validated* = human-reviewed.
+
+---
+
+## Business Context
+
+{{BUSINESS_CONTEXT}}
+
+---
+
+## Actors & Roles
+
+| Actor | Description | Interactions |
+|-------|-------------|-------------|
+{{ACTORS_TABLE}}
+
+---
+
+## Functional Requirements
+
+| ID | Requirement | Priority | Bounded Context |
+|----|-------------|----------|----------------|
+{{FUNCTIONAL_REQUIREMENTS_TABLE}}
+
+---
+
+## Non-Functional Requirements
+
+| ID | Requirement | Category | Target |
+|----|-------------|----------|--------|
+{{NON_FUNCTIONAL_REQUIREMENTS_TABLE}}
+
+---
+
+## Assumptions
+
+| Assumption | Impact if Wrong | Mitigation |
+|------------|----------------|-----------|
+{{ASSUMPTIONS_TABLE}}
+
+---
+
+## Bounded Contexts
+
+| Context | Description | Entities |
+|---------|-------------|----------|
+{{BOUNDED_CONTEXTS_TABLE}}
+
+---
+
+## Entities
+
+| Entity | Context | Type | Description |
+|--------|---------|------|-------------|
+{{ENTITIES_TABLE}}
+
+---
+
+## Domain Events
+
+| Event | Context | Description | Triggered By |
+|-------|---------|-------------|-------------|
+{{DOMAIN_EVENTS_TABLE}}
+
+---
+
+## Ubiquitous Language
+
+| Term | Definition | Bounded Context | Aliases/Synonyms |
+|------|-----------|----------------|-----------------|
+{{UBIQUITOUS_LANGUAGE_TABLE}}
+
+---
+
+## Open Questions
+
+{{OPEN_QUESTIONS}}
+
+---
+
+## Aggregate Roots
+
+{{AGGREGATE_ROOTS}}

package/templates/pi/domain/ubiquitous-language.md

@@ -0,0 +1,24 @@
+# Ubiquitous Language
+
+> Canonical glossary for **[Project Name]**.
+> All code MUST use these terms. Aliases/synonyms listed below are **prohibited** in source identifiers.
+> Drift is detected by `.pi/scripts/validate-ubiquitous-language.sh`.
+
+## Glossary
+
+| Term | Definition | Bounded Context | Aliases/Synonyms | Examples |
+|------|-----------|----------------|-----------------|---------|
+| <!-- Add your terms here --> |  |  |  |  |
+| <!-- Format: | TermName | What it means | ModuleName | Alias1, Alias2 | `code example` | --> |
+
+## Adding New Terms
+
+1. Identify the term used in conversation and code
+2. Add a row to the Glossary table
+3. Define the term's **bounded context** (which module it lives in)
+4. List any **aliases/synonyms** that agents might mistakenly use
+5. Provide **code examples** showing correct usage
+6. Run `.pi/scripts/validate-ubiquitous-language.sh` to detect drift
+
+> **Rule of thumb:** If two agents use different names for the same concept, add an entry.
+> The canonical term is the one used in the architecture module documents.