automatasaurus 0.1.2 → 0.1.4

package/README.md

@@ -246,6 +246,7 @@ your-project/
 │       ├── discovery.md
 │       ├── work.md
 │       ├── work-all.md
+│       ├── work-milestone.md
 │       └── work-plan.md
 └── .claude/
     ├── settings.json            # Claude Code settings (automatasaurus hooks merged in)
@@ -345,6 +346,7 @@ The primary way to invoke workflows:
 | `/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-milestone [milestone#]` | Work through all issues in a specific milestone |
 | `/work [issue#]` | Work on a specific issue |
 
 ### `/discovery` - Discovery Mode
@@ -408,6 +410,24 @@ The orchestrator (aka Product Owner) will:
 - `maxEscalationsBeforeStop`: 3 - Stop if stuck too many times
 - `maxConsecutiveFailures`: 3 - Stop if failing repeatedly
 
+### `/work-milestone` - Milestone-Scoped Work
+
+```
+/work-milestone 3
+```
+
+Work through all open issues in a specific GitHub milestone:
+- Validates the milestone exists and reports its title/open issue count
+- Lists only issues assigned to that milestone
+- Follows `implementation-plan.md` if it exists (filtered to milestone issues)
+- Otherwise uses dependency/priority ordering within the milestone
+- Same circuit breaker limits as `/work-all`
+- Auto-merges successful PRs
+- Reports milestone-specific progress
+- Stops when all issues in the milestone are complete (or limits reached)
+
+Useful when you want to focus on completing a specific release or feature set rather than all open issues.
+
 ### `/work` - Single Issue
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automatasaurus",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Automated software development workflow powered by Claude Code",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -144,6 +144,6 @@ Next steps:
   2. Update .claude/commands.md with your project-specific commands
   3. Start using /discovery, /work, or /work-all commands
 
-Run "automatasaurus status" to see installation details.
+Run "npx automatasaurus status" to see installation details.
 `);
 }

package/src/commands/status.js

@@ -31,7 +31,7 @@ Merged blocks:   ${manifest.merged_blocks.length}
 
   // Check for version mismatch
   if (manifest.version !== currentVersion) {
-    console.log(`Update available! Run "automatasaurus update" to upgrade.\n`);
+    console.log(`Update available! Run "npx automatasaurus update" to upgrade.\n`);
   }
 
   // Check symlink health
@@ -55,7 +55,7 @@ Merged blocks:   ${manifest.merged_blocks.length}
 
   if (brokenCount > 0) {
     console.log(`\nWarning: ${brokenCount} broken symlinks detected.`);
-    console.log('Run "automatasaurus update --force" to repair.\n');
+    console.log('Run "npx automatasaurus update --force" to repair.\n');
   }
 
   // Show merged blocks

package/src/commands/update.js

@@ -16,7 +16,7 @@ export async function update({ force = false } = {}) {
   const manifest = await readManifest(projectRoot);
   if (!manifest) {
     console.log('Automatasaurus is not initialized in this project.');
-    console.log('Run "automatasaurus init" first.');
+    console.log('Run "npx automatasaurus init" first.');
     return;
   }
 

package/template/CLAUDE.block.md

@@ -340,6 +340,45 @@ Notifications are also sent automatically on stop based on context.
 | `AUTOMATASAURUS_SOUND` | Set to "false" to disable notification sounds |
 | `AUTOMATASAURUS_LOG` | Custom log file location |
 
+## Sandbox Configuration
+
+Automatasaurus enables sandbox mode by default for autonomous operation with safety boundaries:
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "mode": "auto-allow",
+    "filesystem": {
+      "writeDeny": ["~/.ssh", "~/.bashrc", "/etc", "/bin", ...]
+    },
+    "network": {
+      "allowedDomains": ["github.com", "npmjs.org", "pypi.org", ...]
+    }
+  }
+}
+```
+
+**Key features:**
+- `auto-allow` mode: Bash commands run without prompts inside sandbox boundaries
+- Protected paths: SSH keys, shell configs, system directories are write-protected
+- Network allowlist: Only approved domains (GitHub, npm, PyPI) accessible
+
+**To add more allowed domains**, add to `settings.local.json`:
+```json
+{
+  "sandbox": {
+    "network": {
+      "allowedDomains": ["your-internal-registry.com"]
+    }
+  }
+}
+```
+
+**Requirements:**
+- macOS: Built-in (Seatbelt)
+- Linux/WSL2: `sudo apt install bubblewrap socat`
+
 ## Circuit Breaker Configuration
 
 Limits are configured in `.claude/settings.json` under `automatasaurus.limits`:

package/template/README.md

@@ -11,7 +11,7 @@ This folder contains the Automatasaurus framework - an automated software develo
 | `agents/` | Specialized AI personas (Developer, Architect, Tester, etc.) |
 | `skills/` | Knowledge modules (coding standards, workflows, etc.) |
 | `hooks/` | Shell scripts for notifications and workflow control |
-| `commands/` | Slash commands (`/discovery`, `/work`, `/work-all`) |
+| `commands/` | Slash commands (`/discovery`, `/work`, `/work-all`, `/work-milestone`) |
 
 ## How It Works
 

package/template/agents/developer/AGENT.md

@@ -83,8 +83,9 @@ Agent: Developer
 8. Run project linter/formatter before commits
 9. Self-review for obvious issues
 10. Check for secrets/credentials (never commit .env, API keys, passwords)
-11. Sync with main and resolve any conflicts
-12. Open PR with comprehensive description
+11. Update README if needed (see README Updates below)
+12. Sync with main and resolve any conflicts
+13. Open PR with comprehensive description
 ```
 
 ---
@@ -128,6 +129,47 @@ Verify your implementation:
 
 ---
 
+## README Updates
+
+Keep the README accurate as you implement changes. Documentation that drifts from reality is worse than no documentation.
+
+### When to Update README
+
+Update the README when your changes affect:
+- **New features** - Add usage examples and configuration options
+- **New commands** - Document command syntax and options
+- **Changed behavior** - Update any descriptions that no longer match
+- **New dependencies** - Add installation or setup steps
+- **Configuration changes** - Document new settings or environment variables
+- **API changes** - Update endpoint documentation, parameters, responses
+
+### When NOT to Update README
+
+Skip README updates for:
+- Internal refactors that don't change external behavior
+- Bug fixes that restore documented behavior
+- Test-only changes
+- Code style/formatting changes
+
+### How to Update
+
+1. **Read the existing README** - understand its structure and style
+2. **Find the right section** - don't duplicate, extend existing sections
+3. **Match the existing style** - use same heading levels, formatting, examples
+4. **Keep it concise** - document what users need, not implementation details
+5. **Include examples** - show, don't just tell
+
+### README Update Checklist
+
+Before committing README changes:
+- [ ] New features have usage examples
+- [ ] Configuration options list is current
+- [ ] Any removed features are removed from docs
+- [ ] Examples actually work (test them)
+- [ ] No TODO comments left in documentation
+
+---
+
 ## Branch Naming
 
 **Format:** `{issue-number}-{descriptive-slug}`

package/template/commands/work-milestone.md

@@ -0,0 +1,327 @@
+# Work Milestone - Process All Issues in a Milestone
+
+Process all open issues in a specific GitHub milestone using context-isolated subagents.
+
+## Usage
+
+```
+/work-milestone {milestone_number}
+```
+
+## Workflow Mode
+
+```
+WORKFLOW_MODE: milestone
+AUTO_MERGE: true (handled by this orchestrator after /work completes)
+```
+
+---
+
+## Instructions
+
+You are the **Milestone Implementation Orchestrator**. You:
+1. Validate the milestone exists and get its details
+2. List all open issues in the milestone
+3. Select issues based on dependencies and priority
+4. Spawn `/work {n}` as a subagent for each issue (context isolation)
+5. Parse subagent output to determine result
+6. Merge successful PRs
+7. Enforce circuit breaker limits
+8. Report milestone-specific progress
+
+---
+
+## Load Context
+
+1. Load the `workflow-orchestration` skill
+2. Load the `github-workflow` skill
+3. Check for `implementation-plan.md` (if exists, filter to milestone issues and follow order)
+4. Read circuit breaker limits from `.claude/settings.json` under `automatasaurus.limits`
+
+---
+
+## Validate Milestone
+
+Before starting, validate the milestone exists:
+
+```bash
+# Get milestone info
+gh api repos/:owner/:repo/milestones/$ARGUMENTS --jq '{title: .title, open_issues: .open_issues, description: .description}'
+```
+
+If milestone doesn't exist or has no open issues, report and exit:
+- Invalid milestone number → Error: "Milestone #X not found"
+- No open issues → Success: "Milestone #X ({title}) has no open issues"
+
+Store milestone info:
+```
+MILESTONE_NUMBER = $ARGUMENTS
+MILESTONE_TITLE = [from API response]
+MILESTONE_TOTAL = [open_issues from API response]
+```
+
+---
+
+## Circuit Breaker Limits
+
+Before each iteration, check limits from settings:
+
+| Limit | Default | Action When Exceeded |
+|-------|---------|---------------------|
+| `maxIssuesPerRun` | 20 | Stop, report progress |
+| `maxEscalationsBeforeStop` | 3 | Stop, notify human |
+| `maxConsecutiveFailures` | 3 | Stop, notify human |
+
+Initialize counters:
+```
+issuesProcessed = 0
+escalationCount = 0
+consecutiveFailures = 0
+successCount = 0
+blockedCount = 0
+```
+
+---
+
+## Main Loop
+
+```
+LOOP:
+  1. CHECK LIMITS
+     - If issuesProcessed >= maxIssuesPerRun → Stop (limit reached)
+     - If escalationCount >= maxEscalationsBeforeStop → Stop (escalation limit)
+     - If consecutiveFailures >= maxConsecutiveFailures → Stop (failure limit)
+
+  2. LIST MILESTONE ISSUES
+     - Use: gh issue list --state open --milestone $ARGUMENTS --json number,title,labels
+     - If no open issues remain → Notify milestone complete, exit
+
+  3. SELECT NEXT ISSUE
+     - If implementation-plan.md exists: filter to milestone issues, follow plan order
+     - Otherwise use selection criteria (see below)
+     - Check dependencies (skip if blocked)
+
+  4. SPAWN /work SUBAGENT
+     - Use Task tool to spawn: "Run /work {issue_number}"
+     - Wait for completion
+     - Parse output for result
+
+  5. PARSE RESULT
+     - SUCCESS: Output contains "PR #X is ready" or "All required reviews complete"
+     - BLOCKED: Output contains "blocked" or "dependency"
+     - ESCALATED: Output contains "Escalating" or "stuck"
+
+  6. HANDLE RESULT
+     - SUCCESS: Merge PR, reset consecutiveFailures, increment issuesProcessed, successCount
+     - BLOCKED: Increment blockedCount, skip issue, continue to next
+     - ESCALATED: Increment escalationCount, consecutiveFailures
+
+  7. REPORT PROGRESS
+     - Show milestone-specific stats
+     - Loop back to step 1
+
+END LOOP
+```
+
+---
+
+## Issue Selection Criteria
+
+### Primary: Follow Implementation Plan
+
+If `implementation-plan.md` exists:
+1. Read the plan
+2. Filter entries to only issues in this milestone (cross-reference with milestone issue list)
+3. Process in plan order
+
+### Fallback: Priority-Based Selection
+
+If no plan exists, select issues by:
+
+#### 1. Dependencies
+- Issues with no open dependencies first
+- Issues that unblock others prioritized
+
+#### 2. Priority Labels
+- `priority:high` → `priority:medium` → `priority:low`
+
+#### 3. Logical Order
+- Foundation (schemas, models) before features
+- Backend before frontend if applicable
+
+---
+
+## Listing Milestone Issues
+
+```bash
+# List all open issues in the milestone
+gh issue list --state open --milestone $ARGUMENTS --json number,title,labels,body
+
+# Check for dependencies in issue body (looks for "depends on #X" or "blocked by #X")
+# Parse each issue to build dependency graph
+```
+
+---
+
+## Spawning Work Subagent
+
+For each selected issue, spawn a subagent that loads and follows the `work-issue` skill.
+
+### Task Tool Parameters
+
+```
+subagent_type: "general-purpose"
+description: "Work on issue #{issue_number}"
+prompt: |
+  Work on GitHub issue #{issue_number}.
+
+  1. Load the `work-issue` skill from .claude/skills/work-issue/SKILL.md
+  2. Follow the skill workflow with ISSUE_NUMBER = {issue_number}
+  3. Execute all steps: dependencies, implementation, reviews
+  4. Report result using the skill's exit state format:
+     - SUCCESS: "PR #X is ready for merge"
+     - BLOCKED: "Issue #{issue_number} is blocked on #Y"
+     - ESCALATED: "Issue #{issue_number} requires human intervention"
+```
+
+### Example Invocation
+
+```
+Use the Task tool with subagent_type "general-purpose" to work on issue #42:
+
+"Work on GitHub issue #42.
+
+Load the work-issue skill from .claude/skills/work-issue/SKILL.md and follow
+the workflow with ISSUE_NUMBER = 42.
+
+Execute all steps: check dependencies, get design specs if UI, implement via
+developer agent, coordinate reviews (Architect, Tester, Designer if UI), handle
+any change requests.
+
+Report result clearly:
+- SUCCESS: 'PR #X is ready for merge'
+- BLOCKED: 'Issue #42 is blocked on #Y'
+- ESCALATED: 'Issue #42 requires human intervention'"
+```
+
+The subagent loads the same skill that `/work` uses, ensuring identical behavior with isolated context.
+
+---
+
+## Result Parsing
+
+After subagent completes, check output for:
+
+**SUCCESS indicators:**
+- "PR #X is ready"
+- "All required reviews complete"
+- "ready for merge"
+
+**BLOCKED indicators:**
+- "blocked"
+- "dependency"
+- "cannot proceed"
+
+**ESCALATED indicators:**
+- "Escalating"
+- "stuck"
+- "requires human"
+- "unable to resolve"
+
+---
+
+## Merge on Success
+
+When result is SUCCESS:
+
+```bash
+# Get PR number from subagent output
+PR_NUMBER=[parsed from output]
+
+# Post verification
+gh pr comment {PR_NUMBER} --body "**[Product Owner]**
+
+All required reviews complete. Proceeding with merge.
+
+Milestone #{MILESTONE_NUMBER}: {MILESTONE_TITLE}
+Issue {issuesProcessed + 1} of {MILESTONE_TOTAL} in milestone"
+
+# Merge
+gh pr merge {PR_NUMBER} --squash --delete-branch
+
+# Verify issue closed
+gh issue view {issue_number} --json state --jq '.state'
+```
+
+---
+
+## Progress Reporting
+
+After each issue:
+
+```
+## Milestone #{MILESTONE_NUMBER}: {MILESTONE_TITLE}
+
+Issue #{number}: [SUCCESS/BLOCKED/ESCALATED]
+Progress: {successCount}/{MILESTONE_TOTAL} issues in milestone complete
+Issues processed this run: {issuesProcessed}/{maxIssuesPerRun}
+Escalations: {escalationCount}/{maxEscalationsBeforeStop}
+```
+
+---
+
+## Stopping Conditions
+
+Stop the loop when ANY of these occur:
+
+1. **Milestone complete** → All issues in milestone processed successfully
+2. **Limit reached** (`maxIssuesPerRun`) → Report progress, suggest continuing later
+3. **Escalation limit** (`maxEscalationsBeforeStop`) → Notify human intervention needed
+4. **Failure limit** (`maxConsecutiveFailures`) → Notify something is wrong
+5. **All remaining issues blocked** → Notify circular dependency or external blocker
+
+---
+
+## Completion Notifications
+
+**Milestone complete:**
+```bash
+.claude/hooks/request-attention.sh complete "Milestone #{MILESTONE_NUMBER} ({MILESTONE_TITLE}) complete! All {MILESTONE_TOTAL} issues merged."
+```
+
+**Limit reached:**
+```bash
+.claude/hooks/request-attention.sh info "Processed {n} issues in milestone #{MILESTONE_NUMBER}. Run /work-milestone {MILESTONE_NUMBER} again to continue."
+```
+
+**Escalation/Failure limit:**
+```bash
+.claude/hooks/request-attention.sh stuck "Stopped after {n} escalations in milestone #{MILESTONE_NUMBER}. Human intervention needed."
+```
+
+---
+
+## Final Summary
+
+When stopping for any reason:
+
+```
+## Work-Milestone Summary
+
+**Milestone:** #{MILESTONE_NUMBER} - {MILESTONE_TITLE}
+**Status:** [Complete / Limit Reached / Stopped - Human Needed]
+
+**Milestone Progress:** {successCount}/{MILESTONE_TOTAL} issues complete
+**Issues Processed This Run:** {issuesProcessed}
+**Successful Merges:** {successCount}
+**Blocked:** {blockedCount}
+**Escalated:** {escalatedCount}
+
+**Remaining in Milestone:** {remaining_count}
+
+[If applicable: Suggest next steps]
+```
+
+---
+
+Begin by validating the milestone number from `$ARGUMENTS`, loading skills, reading limits from settings, then listing all open issues in the milestone.

package/template/settings.json

@@ -10,20 +10,82 @@
   },
   "permissions": {
     "allow": [
-      "Bash(git:*)",
-      "Bash(gh:*)",
-      "Bash(npm:*)",
-      "Bash(npx:*)",
-      "Bash(claude:*)",
-      "Bash(*/.claude/hooks/*)",
+      "Bash(*)",
+      "Read(*)",
+      "Edit(./**)",
+      "Write(./**)",
       "WebSearch"
     ],
     "deny": [
       "Read(./.env)",
       "Read(./.env.*)",
-      "Read(./secrets/**)"
+      "Read(./secrets/**)",
+      "Edit(../)",
+      "Edit(~/**)",
+      "Edit(//etc/**)",
+      "Edit(//var/**)",
+      "Edit(//bin/**)",
+      "Edit(//sbin/**)",
+      "Edit(//usr/**)",
+      "Edit(//System/**)",
+      "Write(../)",
+      "Write(~/**)",
+      "Write(//etc/**)",
+      "Write(//var/**)",
+      "Write(//bin/**)",
+      "Write(//sbin/**)",
+      "Write(//usr/**)",
+      "Write(//System/**)",
+      "Bash(rm -rf ~*)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ../*)",
+      "Bash(rm -r ~*)",
+      "Bash(rm -r /*)",
+      "Bash(rm -r ../*)",
+      "Bash(chmod -R 777 /*)",
+      "Bash(chown -R * /*)"
     ]
   },
+  "sandbox": {
+    "enabled": true,
+    "mode": "auto-allow",
+    "filesystem": {
+      "writeDeny": [
+        "~/.ssh",
+        "~/.gnupg",
+        "~/.bashrc",
+        "~/.zshrc",
+        "~/.profile",
+        "~/.bash_profile",
+        "~/.config/claude",
+        "/etc",
+        "/bin",
+        "/sbin",
+        "/usr/bin",
+        "/usr/sbin",
+        "/System"
+      ]
+    },
+    "network": {
+      "allowedDomains": [
+        "github.com",
+        "api.github.com",
+        "raw.githubusercontent.com",
+        "ghcr.io",
+        "npmjs.org",
+        "registry.npmjs.org",
+        "pypi.org",
+        "files.pythonhosted.org",
+        "docker.io",
+        "registry-1.docker.io",
+        "auth.docker.io",
+        "index.docker.io",
+        "production.cloudflare.docker.com",
+        "gcr.io",
+        "quay.io"
+      ]
+    }
+  },
   "hooks": {
     "Stop": [
       {

package/template/skills/work-issue/SKILL.md

@@ -23,7 +23,8 @@ This skill expects an `ISSUE_NUMBER` to be provided by the caller.
 5. IMPLEMENT → Invoke developer agent with briefing
 6. COORDINATE REVIEWS → Architect (required), Designer (if UI), Tester (required)
 7. HANDLE CHANGE REQUESTS → Loop until all approved
-8. REPORT RESULT → Success, Blocked, or Escalated
+8. COMMIT ORCHESTRATION FILES → Preserve audit trail in branch
+9. REPORT RESULT → Success, Blocked, or Escalated
 ```
 
 ---
@@ -411,7 +412,38 @@ Repeat until all required approvals are present.
 
 ---
 
-## Step 8: Report Result
+## Step 8: Commit Orchestration Files
+
+Before reporting success, commit all briefings and reports to the branch so they're preserved in the PR.
+
+```bash
+# Switch to the issue branch
+BRANCH=$(gh pr view {pr_number} --json headRefName --jq '.headRefName')
+git checkout "$BRANCH"
+
+# Add all orchestration files for this issue
+git add orchestration/issues/{ISSUE_NUMBER}-{slug}/
+
+# Commit with clear message
+git commit -m "docs: add agent orchestration files for #{ISSUE_NUMBER}
+
+Includes briefings and reports from:
+- Designer (if UI)
+- Developer
+- Architect review
+- Tester verification
+
+These provide audit trail of agent coordination."
+
+# Push to the branch
+git push
+```
+
+This ensures the full agent communication history is preserved in the PR and merged with the code.
+
+---
+
+## Step 9: Report Result
 
 ### Check for All Approvals