automatasaurus 0.1.0 → 0.1.2

package/README.md

@@ -25,6 +25,9 @@ claude
 # Review and sequence the implementation plan
 /work-plan
 
+# Generate agent-specific context files
+/contextualize
+
 # Work through all issues autonomously
 /work-all
 ```
@@ -65,6 +68,8 @@ User approves milestone/issue breakdown
     ↓
 User: /work-plan (analyze dependencies, create sequence)
     ↓
+User: /contextualize (generate agent-specific context)
+    ↓
 User: /work-all
 ```
 
@@ -79,27 +84,32 @@ User: /work-all
 │    - Consider priority labels                                       │
 │    - Check circuit breaker limits                                  │
 │                                                                     │
-│ 2. Spawn /work {n} as subagent (context isolation)                 │
+│ 2. Setup orchestration folder                                       │
+│    - Create orchestration/issues/{issue-num}-{slug}/               │
+│    - All agent briefings and reports stored here                   │
+│                                                                     │
+│ 3. Spawn agents with briefings                                      │
 │    └→ Designer: Add specs if UI work needed                        │
+│       (reads BRIEFING-design-specs.md, writes REPORT)              │
 │                                                                     │
-│ 3. Developer: Implement                                             │
+│ 4. Developer: Implement                                             │
+│    - Reads BRIEFING-implement.md (includes prior agent activity)   │
 │    - Create branch: {issue-num}-{slug}                             │
-│    - Commit frequently at logical checkpoints                      │
 │    - If stuck (5 attempts) → Escalate to Architect                 │
-│    - If Architect stuck → Notify human, wait                       │
 │    - Open PR with "Closes #X"                                      │
+│    - Writes REPORT-implement.md                                    │
 │                                                                     │
-│ 4. Review Cycle                                                     │
-│    ├→ Architect: REQUIRED review                                   │
-│    ├→ Designer: Review if UI-relevant (can decline "N/A")          │
+│ 5. Review Cycle (parallel)                                          │
+│    ├→ Architect: REQUIRED review (reads/writes briefing/report)    │
+│    ├→ Designer: Review if UI-relevant                              │
 │    └→ Developer: Address feedback, push fixes                      │
 │                                                                     │
-│ 5. Tester: Verification                                             │
+│ 6. Tester: Verification                                             │
+│    - Reads BRIEFING-test.md (includes all prior reports)           │
 │    - Run automated tests                                            │
-│    - Manual verification if needed (Playwright)                    │
-│    - If issues → Back to Developer                                 │
+│    - Writes REPORT-test.md                                         │
 │                                                                     │
-│ 6. Merge and continue                                               │
+│ 7. Merge and continue                                               │
 │    - Product Owner merges PR                                       │
 │    - Loop until complete or limits reached                         │
 └─────────────────────────────────────────────────────────────────────┘
@@ -110,6 +120,7 @@ User: /work-all
 | Agent | Model | Role | Responsibilities |
 |-------|-------|------|------------------|
 | **Architect** | Opus | Design | System design, ADRs, required PR reviews, stuck-issue analysis |
+| **Contextualizer** | Sonnet | Preparation | Synthesizes discovery/planning into agent-specific PROJECT.md files |
 | **Developer** | Sonnet | Implementation | Feature development, bug fixes, PRs, addresses feedback |
 | **Designer** | Sonnet | Experience | UI/UX specs, accessibility, design reviews (if UI changes) |
 | **Tester** | Sonnet | Quality | Test execution, Playwright verification, required PR reviews |
@@ -122,6 +133,7 @@ All agents prefix their comments with their identity:
 
 ```markdown
 **[Product Owner]** Starting work on issue #5. Routing to Developer.
+**[Contextualizer]** Project context generated for all agents.
 **[Developer]** Fixed in commit abc1234. Ready for re-review.
 **[Architect]** ✅ APPROVED - Architect. Clean separation of concerns.
 **[Designer]** N/A - No UI changes in this PR.
@@ -130,6 +142,7 @@ All agents prefix their comments with their identity:
 
 ## Features
 
+- **Bidirectional Context Flow**: Agents communicate through briefings and reports, creating an audit trail
 - **Stop Hooks**: Intelligent evaluation ensures tasks are complete before stopping
 - **Subagent Coordination**: Specialized agents with role-specific completion criteria
 - **GitHub Integration**: All work coordinated through issues, PRs, and labels
@@ -140,6 +153,45 @@ All agents prefix their comments with their identity:
 - **Project Commands**: Configurable commands for any project stack
 - **Extended Sessions**: Designed for autonomous work over extended periods
 
+## Agent Context Flow
+
+Sub-agents start with fresh context (no conversation history). The orchestration layer uses **briefings** and **reports** to communicate context and capture results.
+
+### How It Works
+
+1. **Parent creates briefing** with task context, constraints, and prior agent activity
+2. **Sub-agent reads briefing** as its first action
+3. **Sub-agent does work** following the briefing instructions
+4. **Sub-agent writes report** before completing (what was done, decisions made, issues encountered)
+5. **Parent reads report** and includes summary in next agent's briefing
+
+This creates a **context chain** where each agent knows what previous agents did.
+
+### Orchestration Folder Structure
+
+All briefings and reports are stored per-issue:
+
+```
+orchestration/
+└── issues/
+    └── 42-user-authentication/
+        ├── BRIEFING-design-specs.md      # Context for Designer
+        ├── REPORT-design-specs.md        # Designer's output
+        ├── BRIEFING-implement.md         # Context for Developer
+        ├── REPORT-implement.md           # Developer's output
+        ├── BRIEFING-architect-review.md  # Context for Architect
+        ├── REPORT-architect-review.md    # Architect's findings
+        ├── BRIEFING-test.md              # Context for Tester
+        └── REPORT-test.md                # Tester's results
+```
+
+### Benefits
+
+- **Audit trail**: Full history of agent communication per issue
+- **Debugging**: Can review what context each agent received
+- **No collisions**: Each agent spawn gets unique files
+- **Informed decisions**: Reviewers see what Developer did, Tester sees all prior activity
+
 ## Prerequisites
 
 - [Claude Code CLI](https://claude.ai/code) installed and authenticated
@@ -165,25 +217,32 @@ After running `npx automatasaurus init`, your project will have:
 ```
 your-project/
 ├── CLAUDE.md                    # Project context (automatasaurus block merged in)
+├── orchestration/               # Agent communication (created during /work)
+│   └── issues/                  # Per-issue briefings and reports
+│       └── 42-user-auth/
+│           ├── BRIEFING-*.md    # Context files for each agent
+│           └── REPORT-*.md      # Output files from each agent
 ├── .automatasaurus/             # Framework files (managed by installer)
 │   ├── README.md                # Framework documentation
 │   ├── agents/                  # AI agents
 │   │   ├── architect/           # Design & required PR reviews
+│   │   ├── contextualizer/      # Agent context generation
 │   │   ├── developer/           # Implementation & PRs
 │   │   ├── designer/            # UI/UX design specs
 │   │   └── tester/              # QA, Playwright, merge authority
 │   ├── skills/                  # Knowledge modules
 │   │   ├── workflow-orchestration/
+│   │   ├── agent-coordination/
+│   │   ├── work-issue/
 │   │   ├── github-workflow/
-│   │   ├── github-issues/
 │   │   ├── python-standards/
-│   │   ├── javascript-standards/
 │   │   ⋮                        # (additional skills)
 │   ├── hooks/                   # Shell scripts for notifications
 │   │   ├── notify.sh
 │   │   ├── on-stop.sh
 │   │   └── request-attention.sh
 │   └── commands/                # Slash command definitions
+│       ├── contextualize.md
 │       ├── discovery.md
 │       ├── work.md
 │       ├── work-all.md
@@ -197,7 +256,7 @@ your-project/
     └── commands/ → .automatasaurus/commands/
 ```
 
-**Note:** Files in `.automatasaurus/` are managed by the installer and updated via `npx automatasaurus update`. Add your own custom agents/skills directly to `.claude/` (not as symlinks).
+**Note:** Files in `.automatasaurus/` are managed by the installer and updated via `npx automatasaurus update`. Add your own custom agents/skills directly to `.claude/` (not as symlinks). The `orchestration/` folder is created during `/work` commands and can optionally be added to `.gitignore`.
 
 ## Installation
 
@@ -284,6 +343,7 @@ The primary way to invoke workflows:
 |---------|-------------|
 | `/discovery [feature]` | Start discovery to understand requirements and create plan |
 | `/work-plan` | Analyze open issues, create sequenced implementation plan |
+| `/contextualize` | Generate agent-specific PROJECT.md context files |
 | `/work-all` | Work through all open issues autonomously |
 | `/work [issue#]` | Work on a specific issue |
 
@@ -314,13 +374,29 @@ Before starting autonomous work, run this command to:
 
 This step helps you review and approve the execution order before `/work-all` begins.
 
+### `/contextualize` - Agent Context Generation
+
+```
+/contextualize
+```
+
+After planning, run this command to prepare each agent with project-specific guidance:
+- Reads `discovery.md` and `implementation-plan.md`
+- Generates tailored `PROJECT.md` files for each agent folder
+- Developer gets implementation guidance, architecture patterns, tech decisions
+- Architect gets review context, NFRs, integration dependencies
+- Designer gets user personas, flows, accessibility requirements
+- Tester gets acceptance criteria, edge cases, test coverage needs
+
+The generated context helps agents make better decisions aligned with your project.
+
 ### `/work-all` - Autonomous Loop
 
 ```
 /work-all
 ```
 
-The orchestrator will:
+The orchestrator (aka Product Owner) will:
 - List all remaining issues
 - Select next issue based on dependencies and priority
 - Spawn `/work {n}` as a subagent for context isolation
@@ -438,22 +514,25 @@ The `.mcp.json` file configures Playwright for browser testing:
 
 ### Circuit Breaker Limits
 
-Configure limits in `.claude/settings.json` under `automatasaurus.limits`:
+Customize limits in `.claude/settings.local.json` (your overrides, never touched by updates):
 
 ```json
 {
   "automatasaurus": {
     "limits": {
-      "maxIssuesPerRun": 20,
-      "maxEscalationsBeforeStop": 3,
-      "maxRetriesPerIssue": 5,
-      "maxConsecutiveFailures": 3
+      "maxIssuesPerRun": 50
     }
   }
 }
 ```
 
-Custom limits survive framework updates (deep merge preserves your values).
+Default values in `.claude/settings.json`:
+- `maxIssuesPerRun`: 20
+- `maxEscalationsBeforeStop`: 3
+- `maxRetriesPerIssue`: 5
+- `maxConsecutiveFailures`: 3
+
+**Note:** Don't edit `settings.json` directly—your changes will be overwritten on update. Use `settings.local.json` for all customizations.
 
 ### Notifications
 
@@ -528,6 +607,14 @@ Contributions welcome:
 - Workflow patterns
 - CLI tool development
 
+## Publishing to npm
+
+```bash
+npm publish --auth-type=web
+```
+
+This opens a browser for authentication (works with passkeys/security keys).
+
 ## References
 
 - [Claude Code Documentation](https://code.claude.com/docs)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "automatasaurus",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Automated software development workflow powered by Claude Code",
   "type": "module",
   "bin": {
-    "automatasaurus": "./bin/cli.js"
+    "automatasaurus": "bin/cli.js"
   },
   "files": [
     "bin/",
@@ -29,7 +29,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shwilliamson/automatasaurus"
+    "url": "git+https://github.com/shwilliamson/automatasaurus.git"
   },
   "homepage": "https://github.com/shwilliamson/automatasaurus#readme",
   "license": "MIT",

package/template/CLAUDE.block.md

@@ -20,7 +20,7 @@ This project uses Automatasaurus, an automated software development workflow pow
 - Tester verifies, then orchestration merges
 - Loop continues until all issues complete or limits reached
 
-**Note:** Commands (`/discovery`, `/work`, `/work-all`) act as the orchestrator. There is no separate PM agent.
+**Note:** Commands (`/discovery`, `/work`, `/work-all`) act as the product owner / orchestrator.
 
 ### Escalation Flow
 
@@ -48,6 +48,7 @@ The following agents are available in `.claude/agents/`:
 | Agent | Role | Model | Review Status |
 |-------|------|-------|---------------|
 | `architect` | System design, ADRs, stuck-issue analysis, PR review | Opus | **Required** |
+| `contextualizer` | PROJECT.md generation, context synthesis | Sonnet | N/A |
 | `designer` | UI/UX specs, accessibility, design review | Sonnet | If UI changes |
 | `developer` | Implementation, PRs, addressing feedback | Sonnet | N/A |
 | `tester` | QA, Playwright, verification | Sonnet | **Required** |
@@ -217,6 +218,7 @@ Primary way to invoke workflows:
 |---------|-------------|
 | `/discovery [feature]` | Start discovery to understand requirements and create plan |
 | `/work-plan` | Analyze open issues, create sequenced implementation plan |
+| `/contextualize` | Generate PROJECT.md files for each agent from discovery/planning |
 | `/work-all` | Work through all open issues autonomously |
 | `/work [issue#]` | Work on a specific issue |
 
@@ -239,6 +241,47 @@ Use the tester agent with playwright to verify the login flow
 
 Or they are automatically selected based on task context.
 
+## Agent Context Flow
+
+Sub-agents start with fresh context - they don't inherit the parent conversation's history. The orchestration layer uses **briefings** and **reports** to communicate context and capture results.
+
+### How It Works
+
+When the `/work` or `/work-all` commands spawn agents, they:
+
+1. **Create a briefing file** with task context and prior agent activity
+2. **Pass the briefing path** in the Task prompt
+3. **Read the agent's report** after the Task returns
+4. **Include report summary** in the next agent's briefing
+
+Agents follow a **briefing protocol** defined in their AGENT.md files:
+1. Read the briefing file first
+2. Do their work
+3. Write a report before completing
+
+### Orchestration Folder Structure
+
+All briefings and reports are stored in `orchestration/`:
+
+```
+orchestration/
+├── discovery/
+│   └── {date}-{feature}/
+├── planning/
+│   └── {date}-{plan}/
+└── issues/
+    └── {issue-number}-{slug}/
+        ├── BRIEFING-design-specs.md
+        ├── REPORT-design-specs.md
+        ├── BRIEFING-implement.md
+        ├── REPORT-implement.md
+        ├── BRIEFING-architect-review.md
+        ├── REPORT-architect-review.md
+        └── ...
+```
+
+This provides a full audit trail of agent communication for each issue.
+
 ## GitHub Integration
 
 This project uses the `gh` CLI for GitHub operations. Ensure you are authenticated:
@@ -257,7 +300,7 @@ Available skills in `.claude/skills/`:
 - `github-issues` - Issue creation, sizing, milestones
 - `pr-writing` - Best practices for writing clear PR descriptions
 - `code-review` - Best practices for performing thorough code reviews
-- `agent-coordination` - Multi-agent workflow patterns
+- `agent-coordination` - Multi-agent workflow patterns and briefing/report protocol
 - `project-commands` - Finding and using project-specific commands
 - `notifications` - User notification system for questions, approvals, and alerts
 

package/template/agents/architect/AGENT.md

@@ -1,7 +1,7 @@
 ---
 name: architect
 description: Software Architect for system design, technical decisions, and code review. Use for reviewing discovery plans, reviewing PRs, or analyzing stuck issues. Required reviewer for all PRs.
-tools: Read, Grep, Glob, Bash, WebSearch
+tools: Read, Edit, Write, Grep, Glob, Bash, WebSearch
 model: opus
 ---
 
@@ -18,6 +18,50 @@ You are a senior Software Architect responsible for technical vision and structu
 
 ---
 
+## Briefing Protocol (When Spawned as Sub-agent)
+
+When you are spawned as a sub-agent, your task prompt will include a briefing file path.
+
+### Reading Your Briefing
+
+1. **Look for the briefing path** in your task prompt (e.g., `orchestration/issues/42-auth/BRIEFING-architect-review.md`)
+2. **Read the briefing first** - it contains:
+   - Your specific task
+   - Context and constraints
+   - Prior agent activity (what Developer did, etc.)
+   - Resources to read as needed
+3. **Follow the briefing** - it tells you exactly what to do
+
+### Writing Your Report
+
+Before completing your work, **write a report** to the path specified in your task prompt:
+
+```markdown
+# Agent Report: {step}
+Completed: {timestamp}
+Agent: Architect
+
+## What Was Done
+- {Review action 1}
+- {Review action 2}
+
+## Key Decisions Made
+- {Decision and rationale}
+
+## Review Result
+{APPROVED / CHANGES REQUESTED / Analysis complete}
+
+## Issues Found
+{List of issues, or "None"}
+
+## Notes for Next Agent
+{Context that would help subsequent reviewers or the developer}
+```
+
+**This report is critical** - it provides context for subsequent agents.
+
+---
+
 ## Discovery Plan Review
 
 When reviewing `discovery.md`, focus on:
@@ -133,8 +177,35 @@ When Developer escalates after 5 attempts:
 
 ---
 
+## Tester Escalations
+
+When Tester escalates architectural concerns (performance, flaky tests, integration issues):
+
+1. **Acknowledge**: Reply to Tester's comment
+2. **Analyze**: Review the test failures in context of architecture
+3. **Provide guidance**: Suggest architectural changes or confirm current approach is correct
+
+```markdown
+**[Architect]** Received Tester escalation. Analyzing test failures.
+
+**Analysis:** [Root cause in architectural terms]
+
+**Recommendation:**
+- [Architectural change if needed]
+- [Or confirmation that current approach is correct]
+```
+
+---
+
 ## ADRs
 
+Create an ADR when:
+- Changing core architectural patterns
+- Adding significant external dependencies
+- Making major refactoring decisions
+- Choosing between competing technical approaches
+- Deviating from established conventions
+
 For significant decisions, create an Architecture Decision Record:
 
 ```markdown

package/template/agents/contextualizer/AGENT.md

@@ -0,0 +1,219 @@
+---
+name: contextualizer
+description: Generate project-specific context files for sub-agents after planning. Synthesizes discovery and implementation plan into tailored guidance for each agent.
+tools: Read, Write, Glob
+model: sonnet
+---
+
+# Contextualizer Agent
+
+You are the Contextualizer, responsible for synthesizing discovery and planning outputs into agent-specific context files. Your job is to prepare each sub-agent with tailored guidance before implementation begins.
+
+## Responsibilities
+
+1. **Read Planning Outputs**: Parse discovery.md and implementation-plan.md
+2. **Analyze Agent Needs**: Understand what each agent type requires
+3. **Generate Context Files**: Create PROJECT.md for each relevant agent
+4. **Maintain Consistency**: Ensure context files align with each other
+
+---
+
+## When to Run
+
+Run Contextualizer after `/discover` and `/plan` complete, before implementation begins. Can also re-run to update PROJECT.md files when planning docs change.
+
+---
+
+## Prerequisites
+
+Before generating context, verify required files exist:
+
+1. **discovery.md** - **Required**. If missing, stop and report:
+   ```markdown
+   **[Contextualizer]** Cannot proceed - discovery.md not found. Run /discover first.
+   ```
+
+2. **implementation-plan.md** - **Required**. If missing, stop and report:
+   ```markdown
+   **[Contextualizer]** Cannot proceed - implementation-plan.md not found. Run /plan first.
+   ```
+
+3. **design-system.md** - **Optional**. If missing, skip design system references in outputs.
+
+---
+
+## Inputs
+
+Read these files before generating context:
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `discovery.md` | Requirements, user flows, technical decisions | Yes |
+| `implementation-plan.md` | Work sequence, dependencies, scope | Yes |
+| `design-system.md` | Design tokens, components, patterns | No |
+
+---
+
+## Outputs
+
+Generate a `PROJECT.md` file in each agent's folder:
+
+```
+.claude/agents/developer/PROJECT.md
+.claude/agents/architect/PROJECT.md
+.claude/agents/designer/PROJECT.md
+.claude/agents/tester/PROJECT.md
+```
+
+---
+
+## Agent-Specific Content Guidelines
+
+Each agent needs different information. Tailor the content accordingly.
+
+### Developer PROJECT.md
+
+Focus on implementation guidance:
+- Key technical decisions from discovery
+- Architecture patterns to follow
+- Data models and schemas
+- API endpoints or interfaces needed
+- Existing utilities and helpers to reuse
+- Technology-specific notes (frameworks, libraries)
+- Reference to design-system.md for UI work
+- Common pitfalls to avoid
+
+### Architect PROJECT.md
+
+Focus on review context:
+- High-level architecture summary
+- Non-functional requirements (performance, security, scalability)
+- Integration dependencies and external systems
+- Technical risks identified during discovery
+- ADR considerations and prior decisions
+- Quality gates and review criteria
+
+### Designer PROJECT.md
+
+Focus on design consistency:
+- User personas and their goals
+- Key user flows from discovery
+- Accessibility requirements (WCAG level)
+- Responsive design breakpoints
+- Brand/design constraints
+- Reference to design-system.md
+- Component patterns to maintain
+
+### Tester PROJECT.md
+
+Focus on verification guidance:
+- Acceptance criteria summary across issues
+- Critical user journeys to verify
+- Edge cases and error states to test
+- Performance testing requirements
+- Integration test scenarios
+- E2E test coverage requirements
+- Known areas of risk to focus on
+
+---
+
+## PROJECT.md Template
+
+Use this structure for each file:
+
+```markdown
+# Project Context for [Agent Name]
+
+Generated: [date]
+Source: discovery.md, implementation-plan.md
+
+## Overview
+
+[Brief project description relevant to this agent's role - 2-3 sentences]
+
+## Key Considerations
+
+[Agent-specific guidance - what matters most for their work]
+
+### [Topic 1]
+[Details]
+
+### [Topic 2]
+[Details]
+
+## Technical Notes
+
+[Relevant technical decisions, constraints, and patterns]
+
+## Reference Documents
+
+- discovery.md - Full requirements and user flows
+- implementation-plan.md - Work sequence and dependencies
+- design-system.md - Design tokens and components (if applicable)
+```
+
+---
+
+## Workflow
+
+Execute these steps in order:
+
+### Step 1: Check Prerequisites
+Verify discovery.md and implementation-plan.md exist. If either is missing, report error and stop.
+
+### Step 2: Read Discovery
+Use the Read tool to read `discovery.md`.
+Extract: requirements, user flows, technical decisions, constraints.
+
+### Step 3: Read Implementation Plan
+Use the Read tool to read `implementation-plan.md`.
+Extract: work sequence, dependencies, scope, risks.
+
+### Step 4: Check for Design System
+Use Glob to check if `design-system.md` exists.
+If it exists, read it and note design tokens and patterns.
+If not, proceed without design system references.
+
+### Step 5: Generate Context Files
+
+For each agent (developer, architect, designer, tester):
+1. Consider what information is relevant to their role
+2. Synthesize from discovery and planning docs
+3. Write PROJECT.md to their folder using the Write tool
+
+### Step 6: Report Completion
+
+```markdown
+**[Contextualizer]** Project context generated for all agents:
+
+| Agent | File | Key Focus |
+|-------|------|-----------|
+| Developer | .claude/agents/developer/PROJECT.md | [summary] |
+| Architect | .claude/agents/architect/PROJECT.md | [summary] |
+| Designer | .claude/agents/designer/PROJECT.md | [summary] |
+| Tester | .claude/agents/tester/PROJECT.md | [summary] |
+
+Agents will now have project-specific guidance when invoked.
+```
+
+---
+
+## Agent Identification
+
+Always use `**[Contextualizer]**` prefix in all outputs:
+
+```markdown
+**[Contextualizer]** Reading discovery and planning documents...
+**[Contextualizer]** Generating project context for Developer agent...
+**[Contextualizer]** Project context generated for all agents.
+```
+
+---
+
+## Guidelines
+
+- **Be concise**: Agents have limited context. Include only what's relevant.
+- **Be specific**: Generic advice is useless. Reference actual project details.
+- **Be consistent**: If you mention a pattern in one agent's context, ensure others align.
+- **Don't duplicate**: Reference source docs rather than copying large sections.
+- **Prioritize**: Put the most important information first.