claude-autopm 3.1.0 → 3.1.2

package/autopm/.claude/rules/context-compaction.md

@@ -0,0 +1,334 @@
+# Context Compaction Rules - MANDATORY
+
+> **CRITICAL**: Apply these compaction strategies to prevent context window exhaustion during long sessions.
+
+## Core Principle
+
+**Context is a finite resource.** Every token matters. Compact aggressively, preserve strategically.
+
+## Automatic Compaction Triggers
+
+### Trigger 1: Tool Result Accumulation
+
+**When**: 10+ tool results in session
+
+**Action**: Summarize older tool results
+
+```markdown
+# BEFORE (consuming ~5000 tokens per result)
+Tool Result 1: [full 500-line file]
+Tool Result 2: [full 300-line file]
+...
+Tool Result 15: [full 200-line file]
+
+# AFTER (consuming ~200 tokens per summary)
+## Compacted Tool Results
+- config.json: DB settings (PostgreSQL:5432), API keys, feature flags
+- src/auth.js: Authentication module with login/logout/validateToken
+- package.json: Node 18, React 18, Express 4, Jest testing
+...
+```
+
+### Trigger 2: Code Block Proliferation
+
+**When**: Same file read 3+ times OR 10+ different files read
+
+**Action**: Consolidate to essential references
+
+```markdown
+# BEFORE
+[src/auth.js - first read - 200 lines]
+[src/auth.js - second read after edit - 205 lines]
+[src/auth.js - third read to verify - 205 lines]
+
+# AFTER
+## src/auth.js Summary
+- Purpose: User authentication with JWT
+- Key functions: login(email, password), validateToken(jwt), refreshToken()
+- Modified sections: lines 45-60 (added MFA check)
+- Current length: 205 lines
+- Last state: MFA integrated, tests passing
+```
+
+### Trigger 3: Thinking Block Growth
+
+**When**: Multiple extended reasoning chains completed
+
+**Action**: Compress to decisions and rationale
+
+```markdown
+# BEFORE
+<thinking>
+Let me analyze this step by step...
+First, I should consider option A because...
+Actually, option B might be better since...
+On further reflection, option A is correct because...
+[500+ tokens of reasoning]
+</thinking>
+
+# AFTER
+## Decision: Option A (Authentication Strategy)
+- Choice: JWT with refresh tokens
+- Rationale: Stateless architecture, better scalability
+- Rejected: Sessions (state management complexity)
+```
+
+### Trigger 4: Conversation Length
+
+**When**: 30+ messages in session
+
+**Action**: Summarize completed topics
+
+```markdown
+# BEFORE
+[Messages 1-15: Debugging authentication issue]
+[Messages 16-25: Implementing MFA]
+[Messages 26-35: Current work on dashboard]
+
+# AFTER
+## Session Summary (Messages 1-25)
+### Completed: Authentication Debugging
+- Issue: Token validation failing on refresh
+- Fix: Updated expiry check in validateToken()
+- PR: #123 merged
+
+### Completed: MFA Implementation
+- Added TOTP support
+- Backup codes generated
+- Tests: 15/15 passing
+
+## Active Context (Messages 26+)
+[Current dashboard implementation work...]
+```
+
+## Compaction Formats
+
+### Format 1: File Summary
+
+```markdown
+## File: [path]
+- Purpose: [one-line description]
+- Key exports: [list main functions/classes]
+- Dependencies: [external dependencies]
+- Modified: [what changed, if applicable]
+- State: [current state/version]
+```
+
+### Format 2: Search Results Summary
+
+```markdown
+## Search: [query]
+- Total matches: [count]
+- Key files: [most relevant files]
+- Pattern: [what the matches reveal]
+- Action needed: [what to do with this info]
+```
+
+### Format 3: Test Results Summary
+
+```markdown
+## Tests: [suite/file]
+- Status: [PASS/FAIL] ([passed]/[total])
+- Failures: [list failing tests if any]
+- Coverage: [percentage if available]
+- Action: [what to fix/investigate]
+```
+
+### Format 4: Decision Record
+
+```markdown
+## Decision: [title]
+- Choice: [what was decided]
+- Rationale: [why, in one sentence]
+- Rejected: [alternatives not chosen]
+- Impact: [what this affects]
+```
+
+## Preservation Rules
+
+### ALWAYS Preserve
+
+1. **Active Task Context**
+   - Current file being edited
+   - Unsaved changes
+   - Active error messages
+
+2. **Critical Decisions**
+   - Architectural choices
+   - Security configurations
+   - Breaking changes
+
+3. **Blocking Issues**
+   - Current errors
+   - Failing tests
+   - Unresolved dependencies
+
+4. **User Requirements**
+   - Original request
+   - Constraints specified
+   - Preferences stated
+
+### SAFE to Compact
+
+1. **Historical Tool Results**
+   - Files read 5+ messages ago
+   - Search results already acted upon
+   - Test results from passing suites
+
+2. **Superseded Information**
+   - Old file versions
+   - Rejected approaches
+   - Fixed bugs
+
+3. **Verbose Output**
+   - Full stack traces (keep summary)
+   - Build logs (keep errors only)
+   - Long lists (keep relevant items)
+
+4. **Exploratory Work**
+   - Hypothesis testing completed
+   - Alternative approaches evaluated
+   - Research phase findings
+
+## Implementation Patterns
+
+### Pattern 1: Progressive Summarization
+
+```markdown
+# Level 0: Full content (initial read)
+[Complete file: 500 lines]
+
+# Level 1: Key sections (after analysis)
+## Key Sections in config.json
+- Database config (lines 1-50)
+- API settings (lines 51-100)
+- Feature flags (lines 101-150)
+
+# Level 2: Actionable summary (after decision)
+config.json: Using PostgreSQL on 5432, rate limit 100/min, darkMode enabled
+```
+
+### Pattern 2: Rolling Window
+
+Keep last N items in full detail, summarize older:
+
+```markdown
+## Recent (full detail)
+- Tool Result 8: [full content]
+- Tool Result 9: [full content]
+- Tool Result 10: [full content]
+
+## Historical (summarized)
+- Results 1-7: config files read, auth system analyzed,
+  tests confirmed passing, dependencies validated
+```
+
+### Pattern 3: Topic-Based Grouping
+
+Group related items for efficient summarization:
+
+```markdown
+## Authentication Work (compacted)
+Files read: src/auth.js, src/middleware/auth.js, src/models/User.js
+Changes made: Added MFA support (auth.js:45-60)
+Tests: 15/15 passing
+Outcome: MFA feature complete
+
+## Database Work (compacted)
+Files read: src/db/connection.js, migrations/*.js
+Changes made: Added index on users.email
+Tests: 8/8 passing
+Outcome: Query performance improved 40%
+```
+
+## Enforcement
+
+### Self-Check Questions
+
+Before adding new content, ask:
+1. Is this information already in context (in another form)?
+2. Will this be needed after the current operation?
+3. Can this be summarized without losing actionable details?
+4. Does this duplicate information from another tool result?
+
+### Compaction Checklist
+
+When context feels heavy:
+- [ ] Summarize tool results older than 5 messages
+- [ ] Compress completed reasoning chains
+- [ ] Consolidate multiple reads of same file
+- [ ] Remove superseded information
+- [ ] Group related items into summaries
+
+### Warning Signs
+
+**Immediate Action Needed:**
+- Response times noticeably slower
+- "Context too long" errors
+- Repetitive information in context
+- Multiple versions of same file
+- 50+ messages without compaction
+
+## Integration with /clear
+
+### When to Compact vs Clear
+
+| Situation | Action |
+|-----------|--------|
+| Same task, growing context | Compact |
+| Task complete, starting new | /clear |
+| Context heavy but continuity needed | Compact + Checkpoint |
+| Unrelated topics mixing | /clear |
+| Long research session | Compact progressively |
+
+### Handoff Pattern
+
+Before `/clear`, create transfer summary:
+
+```markdown
+## Session Transfer Summary
+
+### Completed
+- [list completed items]
+
+### In Progress
+- [current state]
+
+### Preserved Context
+- [critical information for next session]
+
+### Next Steps
+- [what to do next]
+```
+
+## Metrics
+
+### Context Efficiency Score
+
+Calculate: (Useful tokens / Total tokens) × 100
+
+- **>80%**: Excellent - minimal waste
+- **60-80%**: Good - some optimization possible
+- **40-60%**: Fair - compaction recommended
+- **<40%**: Poor - immediate compaction needed
+
+### Token Budget Guidelines
+
+| Session Type | Recommended Budget |
+|--------------|-------------------|
+| Quick fix | <20k tokens |
+| Feature implementation | <50k tokens |
+| Complex debugging | <80k tokens |
+| Full project work | <100k tokens + checkpoints |
+
+## Summary
+
+**Golden Rules:**
+1. Compact early, compact often
+2. Preserve decisions, discard deliberation
+3. Summarize verbose output immediately
+4. Use progressive summarization
+5. Create checkpoints for long work
+6. /clear between unrelated tasks
+
+**Remember**: A well-compacted context leads to better responses, faster processing, and more productive sessions.

package/autopm/.claude/templates/memory/active-work.template.json

@@ -0,0 +1,15 @@
+{
+  "current_task": {
+    "id": "",
+    "title": "",
+    "branch": "",
+    "started": "",
+    "status": "pending"
+  },
+  "recent_changes": [],
+  "blockers": [],
+  "next_steps": [],
+  "context_notes": "",
+  "decisions_made": [],
+  "files_of_interest": []
+}

package/autopm/.claude/templates/memory/checkpoint.template.md

@@ -0,0 +1,58 @@
+# Checkpoint: {{FEATURE_NAME}}
+
+**Date**: {{TIMESTAMP}}
+**Session**: {{SESSION_NUMBER}}
+
+## Status Summary
+
+- **Overall Progress**: {{PERCENTAGE}}% complete
+- **Tests**: {{TESTS_PASSING}}/{{TESTS_TOTAL}} passing
+- **Branch**: {{BRANCH_NAME}}
+- **Last Commit**: {{COMMIT_HASH}}
+
+## Completed Items
+
+- [x] {{COMPLETED_ITEM_1}}
+- [x] {{COMPLETED_ITEM_2}}
+
+## In Progress
+
+- [ ] {{IN_PROGRESS_ITEM}} - {{CURRENT_STATE}}
+
+## Pending
+
+- [ ] {{PENDING_ITEM_1}}
+- [ ] {{PENDING_ITEM_2}}
+
+## Key Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {{DECISION_1}} | {{CHOICE_1}} | {{RATIONALE_1}} |
+
+## Critical Context
+
+- {{CRITICAL_INFO_1}}
+- {{CRITICAL_INFO_2}}
+
+## Files Modified This Session
+
+- `{{FILE_1}}` - {{CHANGE_DESCRIPTION_1}}
+- `{{FILE_2}}` - {{CHANGE_DESCRIPTION_2}}
+
+## Commands to Resume
+
+```bash
+git checkout {{BRANCH_NAME}}
+npm install
+npm run dev
+# Then: "Continue {{FEATURE_NAME}} implementation"
+```
+
+## Notes for Next Session
+
+- {{NOTE_1}}
+- {{NOTE_2}}
+
+---
+*Generated by context-optimizer agent*

package/lib/cli/commands/prd.js

@@ -301,11 +301,91 @@ async function prdStatus(argv) {
   }
 }
 
+/**
+ * Create new PRD from content (non-interactive mode)
+ * @param {Object} argv - Command arguments
+ */
+async function prdNewFromContent(argv) {
+  const spinner = ora(`Creating PRD: ${argv.name}`).start();
+
+  try {
+    let content = argv.content;
+
+    // Check if content is a file reference (starts with @)
+    if (content.startsWith('@')) {
+      const filePath = content.slice(1); // Remove @ prefix
+      const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.join(process.cwd(), filePath);
+
+      const fileExists = await fs.pathExists(absolutePath);
+      if (!fileExists) {
+        spinner.fail(chalk.red('Source file not found'));
+        console.error(chalk.red(`\nError: File not found: ${absolutePath}`));
+        process.exit(1);
+      }
+
+      content = await fs.readFile(absolutePath, 'utf8');
+      spinner.text = `Reading content from: ${absolutePath}`;
+    }
+
+    // Ensure PRDs directory exists
+    const prdsDir = path.join(process.cwd(), '.claude', 'prds');
+    await fs.ensureDir(prdsDir);
+
+    // Check if PRD already exists
+    const prdPath = getPrdPath(argv.name);
+    const exists = await fs.pathExists(prdPath);
+    if (exists && !argv.force) {
+      spinner.fail(chalk.red('PRD already exists'));
+      console.error(chalk.red(`\nError: PRD file already exists: ${prdPath}`));
+      console.error(chalk.yellow('Use --force to overwrite'));
+      process.exit(1);
+    }
+
+    // Add frontmatter if not present
+    if (!content.startsWith('---')) {
+      const timestamp = new Date().toISOString();
+      const frontmatter = `---
+title: ${argv.name}
+status: draft
+priority: ${argv.priority || 'P2'}
+created: ${timestamp}
+author: ${process.env.USER || 'unknown'}
+timeline: ${argv.timeline || 'TBD'}
+---
+
+`;
+      content = frontmatter + content;
+    }
+
+    // Write PRD file
+    await fs.writeFile(prdPath, content);
+    spinner.succeed(chalk.green('PRD created successfully'));
+
+    console.log(chalk.green(`\n✅ PRD created: ${prdPath}`));
+    console.log(chalk.cyan('\n📋 Next steps:'));
+    console.log(`  1. Review: ${chalk.yellow('autopm prd show ' + argv.name)}`);
+    console.log(`  2. Edit:   ${chalk.yellow('autopm prd edit ' + argv.name)}`);
+    console.log(`  3. Parse:  ${chalk.yellow('autopm prd parse ' + argv.name)}`);
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to create PRD'));
+    console.error(chalk.red(`\nError: ${error.message}`));
+    process.exit(1);
+  }
+}
+
 /**
  * Create new PRD
  * @param {Object} argv - Command arguments
  */
 async function prdNew(argv) {
+  // Check if content is provided (non-interactive mode)
+  if (argv.content) {
+    return await prdNewFromContent(argv);
+  }
+
   // Check if AI mode is enabled
   if (argv.ai) {
     return await prdNewWithAI(argv);
@@ -803,7 +883,7 @@ function builder(yargs) {
     )
     .command(
       'new <name>',
-      'Create new PRD interactively',
+      'Create new PRD interactively or from existing content',
       (yargs) => {
         return yargs
           .positional('name', {
@@ -815,6 +895,27 @@ function builder(yargs) {
             type: 'string',
             alias: 't'
           })
+          .option('content', {
+            describe: 'PRD content: inline text or @filepath to read from file (non-interactive)',
+            type: 'string',
+            alias: 'c'
+          })
+          .option('force', {
+            describe: 'Overwrite existing PRD file',
+            type: 'boolean',
+            alias: 'f',
+            default: false
+          })
+          .option('priority', {
+            describe: 'PRD priority (P0/P1/P2/P3)',
+            type: 'string',
+            alias: 'p',
+            default: 'P2'
+          })
+          .option('timeline', {
+            describe: 'PRD timeline (e.g., Q1 2025)',
+            type: 'string'
+          })
           .option('ai', {
             describe: 'Use AI to generate PRD content (requires ANTHROPIC_API_KEY)',
             type: 'boolean',
@@ -827,6 +928,8 @@ function builder(yargs) {
           })
           .example('autopm prd new my-feature', 'Create PRD with wizard')
           .example('autopm prd new payment-api --template api-feature', 'Create PRD from template')
+          .example('autopm prd new my-feature --content @/path/to/draft.md', 'Create from file')
+          .example('autopm prd new my-feature --content "# My PRD\\n\\nDescription..."', 'Create from inline')
           .example('autopm prd new my-feature --ai', 'AI-powered PRD generation')
           .example('autopm prd new my-feature --ai --stream', 'AI generation with streaming');
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-autopm",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Autonomous Project Management Framework for Claude Code - Advanced AI-powered development automation",
   "main": "bin/autopm.js",
   "workspaces": [

package/packages/plugin-pm/commands/pm:epic-decompose.md

@@ -6,6 +6,11 @@ allowed-tools: Bash, Read, Write, LS, Task
 
 Break epic into concrete, actionable tasks.
 
+**⚠️ IMPORTANT**: This is a Claude Code command file, not a standalone script.
+- Execute via Claude Code as: `/pm:epic-decompose <feature_name>`
+- Do NOT run as: `node .claude/scripts/pm/epic-decompose.js`
+- This command has no standalone script equivalent
+
 ## Usage
 
 **Single Epic:**

package/packages/plugin-pm/commands/pm:issue-start.md

@@ -24,14 +24,10 @@ Begin work on a GitHub issue with parallel agents based on work stream analysis.
    - If not found, search for file containing `github:.*issues/$ARGUMENTS` in frontmatter (old naming)
    - If not found: "❌ No local task for issue #$ARGUMENTS. This issue may have been created outside the PM system."
 
-3. **Check for analysis:**
-   ` ``bash
-   test -f .claude/epics/*/$ARGUMENTS-analysis.md || echo "❌ No analysis found for issue #$ARGUMENTS
-   
-   Run: /pm:issue-analyze $ARGUMENTS first
-   Or: /pm:issue-start $ARGUMENTS --analyze to do both"
-   ` ``
-   If no analysis exists and no --analyze flag, stop execution.
+3. **Check for analysis (when NOT using --analyze flag):**
+   - If user didn't use `--analyze` flag, check if analysis file exists
+   - Analysis file location: `.claude/epics/{epic_name}/$ARGUMENTS-analysis.md`
+   - If no analysis AND no `--analyze` flag: Stop and suggest using `--analyze` flag
 
 ## Required Documentation Access
 
@@ -71,7 +67,25 @@ See `.claude/rules/tdd.enforcement.md` for complete TDD requirements.
 
 ## Instructions
 
-### 1. Ensure Branch Exists
+### 0. Handle --analyze Flag (if provided)
+
+If user provided `--analyze` flag, delegate to the Node.js script:
+` ``bash
+node packages/plugin-pm/scripts/pm/issue-start.cjs $ARGUMENTS --analyze
+` ``
+
+This script will:
+1. Find the task file for the issue
+2. Generate analysis file with parallel work streams
+3. Create workspace structure
+4. Launch parallel agents based on analysis
+5. Handle all subsequent steps automatically
+
+**STOP HERE** if using `--analyze` flag - the script handles everything.
+
+---
+
+### 1. Ensure Branch Exists (Non-analyze workflow)
 
 Check if epic branch exists:
 ` ``bash