aicodeman 0.2.8

package/dist/templates/case-template.md

@@ -0,0 +1,461 @@
+# CLAUDE.md - Project Configuration
+
+## Setup
+Copy these files to your new project:
+- `CLAUDE.md` → project root
+- `.claude/settings.json` → `.claude/settings.json`
+
+Then update the Project Overview section below.
+
+---
+
+## Project Overview
+<!-- Update this section with project-specific details -->
+- **Project Name**: [PROJECT_NAME]
+- **Description**: [PROJECT_DESCRIPTION]
+- **Tech Stack**: [TECHNOLOGIES_USED]
+- **Last Updated**: [DATE]
+
+---
+
+## Codeman Environment
+
+This session is managed by **Codeman** and runs within a tmux session.
+
+**Important**: Check for `CODEMAN_MUX=1` environment variable to confirm.
+- Do NOT attempt to kill your own tmux session
+- The session persists across disconnects - your work is safe
+- Token usage, costs, and background tasks are tracked externally
+
+---
+
+## Work Principles
+
+### Autonomy
+Full permissions granted. Act decisively without asking - read, write, edit, execute freely.
+
+### Git Discipline
+- **Commit after every meaningful change** - never batch unrelated work
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- Commit message = what changed + why (not how)
+
+### Documentation
+- Update README.md when adding features or changing setup
+- Update this file's session log after work sessions
+- Keep docs in sync with code changes
+
+### Thinking
+Extended thinking is enabled. Use deep reasoning for complex architectural decisions, difficult bugs, and multi-file changes.
+
+### Task Tracking (TodoWrite)
+**ALWAYS use TodoWrite** to track tasks. This is non-negotiable for anything beyond trivial single-step work.
+
+**When to use TodoWrite:**
+- Multi-step tasks (3+ steps)
+- Bug fixes requiring investigation
+- Feature implementations
+- Any work where progress tracking helps
+- When the user provides multiple requests
+
+**How to use it:**
+1. **Before starting**: Break down the work into discrete todos
+2. **During work**: Mark each todo `in_progress` before starting, `completed` when done
+3. **One at a time**: Only ONE todo should be `in_progress` at any moment
+4. **Immediately**: Mark todos complete the moment they're done - don't batch
+
+**Why this matters:**
+- Gives the user visibility into your progress
+- Prevents forgetting tasks mid-work
+- Creates accountability checkpoints
+- Makes complex work manageable
+
+**Example workflow:**
+```
+User: "Add user authentication with JWT"
+
+→ TodoWrite:
+  - [ ] Research existing auth patterns in codebase
+  - [ ] Implement JWT token generation
+  - [ ] Add login endpoint
+  - [ ] Add token validation middleware
+  - [ ] Add protected route example
+  - [ ] Write tests
+
+→ Mark "Research existing auth patterns" as in_progress
+→ Do the research
+→ Mark as completed, mark next as in_progress
+→ Continue until all done
+```
+
+**Anti-patterns to avoid:**
+- Starting work without creating todos first
+- Having multiple todos `in_progress` simultaneously
+- Batching completions at the end
+- Skipping TodoWrite for "simple" multi-step tasks
+
+---
+
+## When to Use Agents
+
+**Explore agent**: Codebase investigation, finding files, understanding architecture
+```
+"Use explore agent to find all authentication-related code"
+```
+
+**Parallel agents**: Independent tasks that don't conflict
+```
+"Research auth, database, and API modules in parallel using separate agents"
+```
+
+**Background execution**: Long-running operations (tests, builds)
+```
+"Run the test suite in the background while I continue"
+```
+
+**Sequential chaining**: When second task depends on first
+```
+"Use code-reviewer to find issues, then use fixer to resolve them"
+```
+
+---
+
+## Planning Mode (Automatic)
+
+**Automatically enter planning mode** when ANY of these conditions apply:
+- Multi-file changes (3+ files affected)
+- Architectural decisions
+- Unclear or evolving requirements
+- Risk mitigation on core systems
+- New feature implementation
+- Refactoring existing functionality
+
+**Do NOT ask** whether to enter planning mode - just enter it when conditions are met.
+
+Planning mode flow: read-only exploration → create plan → get approval → execute.
+
+**Skip planning mode** only for:
+- Single-file bug fixes
+- Typo corrections
+- Simple config changes
+- Tasks with explicit step-by-step instructions from user
+
+---
+
+## Ralph Wiggum Loop (Autonomous Work Mode)
+
+Ralph loops enable persistent, autonomous work on large tasks. When active, you continue iterating until completion criteria are met or the loop is cancelled.
+
+### Starting a Ralph Loop
+- Start: `/ralph-loop:ralph-loop`
+- Cancel: `/ralph-loop:cancel-ralph`
+- Help: `/ralph-loop:help`
+
+### Time-Aware Loops
+
+When the user specifies a **minimum duration** (e.g., "optimize for 8 hours", "work on this for 2 hours"), the loop becomes time-aware:
+
+**At loop start:**
+```bash
+# Record start time
+date +%s > /tmp/ralph_start_time
+echo "Loop started at $(date)"
+```
+
+**Check elapsed time periodically:**
+```bash
+START=$(cat /tmp/ralph_start_time)
+NOW=$(date +%s)
+ELAPSED_HOURS=$(echo "scale=2; ($NOW - $START) / 3600" | bc)
+echo "Elapsed: $ELAPSED_HOURS hours"
+```
+
+**Time-aware behavior:**
+1. Complete all primary tasks from the user's prompt
+2. After primary tasks done, check elapsed time
+3. If minimum duration NOT reached:
+   - **Do NOT output completion phrase**
+   - Self-generate additional related tasks
+   - Continue working until minimum time elapsed
+4. Only output completion phrase when:
+   - ALL primary tasks complete AND
+   - Minimum duration reached (or exceeded)
+
+**Self-generating additional tasks when time remains:**
+- Code optimization (performance, readability, DRY)
+- Test coverage improvements
+- Edge case handling
+- Error message improvements
+- Documentation gaps
+- Security hardening
+- Accessibility improvements
+- Code cleanup and dead code removal
+- Dependency updates
+- Type safety improvements
+
+**Example time-aware prompt:**
+```
+"Optimize the API endpoints for the next 4 hours. Focus on performance first,
+then code quality. Minimum runtime: 4 hours."
+Completion phrase: <promise>TIME_COMPLETE</promise>
+```
+
+**Time-aware loop behavior:**
+```
+[Start loop, record timestamp]
+[Complete primary optimization tasks - 2 hours elapsed]
+[Check time: 2/4 hours - NOT done yet]
+[Self-generate: "Add caching to database queries"]
+[Self-generate: "Optimize N+1 queries"]
+[Self-generate: "Add request batching"]
+[Continue working... 4.5 hours elapsed]
+[Check time: 4.5/4 hours - minimum reached]
+[All tasks complete, tests pass]
+<promise>TIME_COMPLETE</promise>
+```
+
+### How You Know You're in a Ralph Loop
+
+The user started the loop with a prompt containing:
+- Clear task requirements
+- A **completion phrase** (e.g., `<promise>COMPLETE</promise>`)
+- **Optional: minimum duration** (e.g., "for the next 4 hours")
+- Iteration limits (handled by the system)
+
+Your job: Keep working until ALL requirements are verifiably done AND minimum time reached (if specified), then output the exact completion phrase.
+
+### Core Behaviors During Ralph Loop
+
+**1. Work Incrementally**
+- Complete one sub-task at a time
+- Verify it works before moving to the next
+- Don't try to do everything in one pass
+
+**2. Commit Frequently**
+- Commit after each meaningful completion
+- Creates recovery points if something breaks
+- Shows progress in git history
+```
+git add . && git commit -m "feat(auth): add token refresh endpoint"
+```
+
+**3. Self-Correct Relentlessly**
+```
+Loop:
+  1. Implement/fix
+  2. Run tests
+  3. If tests fail → read error, fix, go to 1
+  4. Run linter
+  5. If lint errors → fix, go to 1
+  6. Commit
+  7. Continue to next task
+```
+
+**4. Track Progress**
+Update the session log in this file as you complete tasks:
+```markdown
+| Date | Tasks Completed | Files Changed | Notes |
+|------|-----------------|---------------|-------|
+| YYYY-MM-DD | Add auth endpoint | auth.ts, routes.ts | Tests passing |
+```
+
+**5. Use Git History When Stuck**
+If something isn't working:
+```bash
+git log --oneline -10
+git diff HEAD~1
+```
+See what you already tried. Don't repeat failed approaches.
+
+**6. Completion Phrase = Contract**
+Only output the completion phrase (e.g., `<promise>COMPLETE</promise>`) when:
+- ALL requirements from the original prompt are done
+- ALL tests pass
+- ALL linting passes
+- Changes are committed
+
+**Never output the completion phrase early.** The loop only ends when you say it's done.
+
+### What Makes Good Completion Criteria
+
+The user should provide criteria that are:
+- **Verifiable**: Tests pass, lint clean, build succeeds
+- **Measurable**: "5 endpoints", "all files in src/", "zero errors"
+- **Binary**: Done or not done, no ambiguity
+
+If the original prompt has vague criteria, ask clarifying questions before starting heavy work.
+
+### Self-Correction Pattern (Include in Your Work)
+
+```
+FOR EACH TASK:
+1. Implement the change
+2. Run tests (npm test, pytest, go test, cargo test, etc.)
+   - If fail → read error, fix, retry
+3. Run linter (npm run lint, ruff, golangci-lint, etc.)
+   - If fail → fix, go to step 2
+4. Verify manually if needed
+5. Commit with descriptive message
+6. Update session log
+7. Move to next task
+
+WHEN ALL TASKS DONE:
+1. Run full test suite
+2. Run full lint
+3. Verify build succeeds
+4. Review all changes: git diff main
+5. Only then output completion phrase
+```
+
+### Example: How to Think During Ralph Loop
+
+**Original prompt**: "Add CRUD endpoints for todos with validation"
+
+**Your approach**:
+```
+Task breakdown:
+- [ ] GET /todos (list)
+- [ ] POST /todos (create with validation)
+- [ ] GET /todos/:id (single)
+- [ ] PUT /todos/:id (update with validation)
+- [ ] DELETE /todos/:id
+- [ ] Tests for all endpoints
+
+Starting with GET /todos...
+[implement]
+[test - passes]
+[commit: "feat(todos): add GET /todos endpoint"]
+[update session log]
+
+Moving to POST /todos...
+[implement]
+[test - fails: validation not working]
+[fix validation]
+[test - passes]
+[commit: "feat(todos): add POST /todos with validation"]
+[update session log]
+
+...continue until all done...
+
+Final verification:
+[npm test - all pass]
+[npm run lint - clean]
+[npm run build - succeeds]
+
+<promise>COMPLETE</promise>
+```
+
+### When to NOT Output Completion Phrase
+
+- Tests are failing (even one)
+- Lint errors exist
+- Build is broken
+- You skipped a requirement
+- You're unsure if something works
+- **Minimum duration not reached** (for time-aware loops)
+
+Instead: Fix the issue, verify, then complete. For time-aware loops: generate more tasks and keep improving until minimum time elapsed.
+
+### RALPH_STATUS Block (Required During Ralph Loop)
+
+At the **END of every response** during a Ralph Loop, output this structured status block:
+
+```
+---RALPH_STATUS---
+STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+TASKS_COMPLETED_THIS_LOOP: <number>
+FILES_MODIFIED: <number>
+TESTS_STATUS: PASSING | FAILING | NOT_RUN
+WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
+EXIT_SIGNAL: false | true
+RECOMMENDATION: <one line summary of what to do next>
+---END_RALPH_STATUS---
+```
+
+**Rules:**
+- Output this block at the end of **every** response, no exceptions
+- Set `EXIT_SIGNAL` to `true` ONLY when ALL tasks are verifiably done
+- Set `STATUS` to `BLOCKED` when you need human intervention
+- Do NOT continue with busy work when `EXIT_SIGNAL` should be `true`
+- Do NOT forget the status block — it is required for loop tracking
+
+### Testing Limits
+
+- **LIMIT testing to ~20% of total effort** per loop
+- PRIORITIZE: Implementation > Documentation > Tests
+- Only write tests for NEW functionality
+- Do NOT refactor existing tests unless broken
+- Do NOT run tests repeatedly without implementing new features
+
+### Exit Scenarios (When to Set EXIT_SIGNAL)
+
+| Scenario | STATUS | EXIT_SIGNAL | Action |
+|----------|--------|-------------|--------|
+| All tasks completed, tests pass | COMPLETE | true | Output completion phrase |
+| No work remaining, specs done | COMPLETE | true | Output completion phrase |
+| Making normal progress | IN_PROGRESS | false | Continue to next task |
+| Test-only loop (no implementation) | IN_PROGRESS | false | Warn and shift to implementation |
+| Stuck on same error repeatedly | BLOCKED | false | Describe blocker, request help |
+| Needs human decision/intervention | BLOCKED | false | Describe what's needed |
+
+**Anti-patterns to avoid:**
+- Setting `EXIT_SIGNAL: true` when tests are failing
+- Continuing to work when all tasks are genuinely done (busy work)
+- Running the same failing test repeatedly without changing approach
+- Adding features not in the original specifications
+- Refactoring working code instead of completing assigned tasks
+
+---
+
+## Code Standards
+
+### Before Writing
+- Read existing code in the area you're modifying
+- Follow existing patterns and conventions
+- Check for similar implementations to reference
+
+### During Implementation
+- Keep changes focused and minimal
+- Don't over-engineer
+- Write tests for new functionality
+
+### After Implementation
+- Run tests
+- Update docs if needed
+- Commit with descriptive message
+
+---
+
+## Hooks Awareness
+
+This project may have hooks that auto-format code after writes or validate operations. If a tool call behaves unexpectedly, hooks are likely the cause. Continue working - they're intentional.
+
+---
+
+## Session Log
+
+| Date | Tasks Completed | Files Changed | Notes |
+|------|-----------------|---------------|-------|
+| [DATE] | Project created | CLAUDE.md | Initial setup |
+
+---
+
+## Current Task Queue
+
+### Active Ralph Loop
+**Status**: Not Active
+**Completion Phrase**: -
+
+### Pending Tasks
+- [ ] <!-- Add tasks here -->
+
+---
+
+## Implementation Plans
+
+<!-- Document plans before major implementations -->
+
+---
+
+## Notes & Decisions
+
+<!-- Track important decisions and context -->

package/dist/templates/claude-md.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview CLAUDE.md template generation
+ *
+ * Generates CLAUDE.md configuration files for new Codeman projects.
+ * Reads the bundled case-template.md and performs placeholder substitution.
+ * Supports custom templates via settings.json override.
+ *
+ * @module templates/claude-md
+ */
+/**
+ * Generates a CLAUDE.md configuration file for a new project.
+ *
+ * Priority order for template resolution:
+ * 1. Custom template via `templatePath` parameter (from settings.json)
+ * 2. Bundled `case-template.md` (shipped with the project)
+ * 3. Minimal fallback (if bundled template is missing)
+ *
+ * Placeholders replaced: [PROJECT_NAME], [PROJECT_DESCRIPTION], [DATE]
+ *
+ * @param caseName - The project/case name to use in the template
+ * @param description - Optional project description (defaults to "A new project")
+ * @param templatePath - Optional path to a custom template file (from settings.json)
+ * @returns The generated CLAUDE.md content
+ */
+export declare function generateClaudeMd(caseName: string, description?: string, templatePath?: string): string;
+//# sourceMappingURL=claude-md.d.ts.map

package/dist/templates/claude-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../../src/templates/claude-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAAW,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB1G"}

package/dist/templates/claude-md.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview CLAUDE.md template generation
+ *
+ * Generates CLAUDE.md configuration files for new Codeman projects.
+ * Reads the bundled case-template.md and performs placeholder substitution.
+ * Supports custom templates via settings.json override.
+ *
+ * @module templates/claude-md
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_TEMPLATE_PATH = join(__dirname, 'case-template.md');
+const MINIMAL_FALLBACK = `# CLAUDE.md - Project Configuration
+
+## Project Overview
+- **Project Name**: [PROJECT_NAME]
+- **Description**: [PROJECT_DESCRIPTION]
+- **Last Updated**: [DATE]
+
+## Session Log
+
+| Date | Tasks Completed | Files Changed | Notes |
+|------|-----------------|---------------|-------|
+| [DATE] | Project created | CLAUDE.md | Initial setup |
+`;
+/**
+ * Generates a CLAUDE.md configuration file for a new project.
+ *
+ * Priority order for template resolution:
+ * 1. Custom template via `templatePath` parameter (from settings.json)
+ * 2. Bundled `case-template.md` (shipped with the project)
+ * 3. Minimal fallback (if bundled template is missing)
+ *
+ * Placeholders replaced: [PROJECT_NAME], [PROJECT_DESCRIPTION], [DATE]
+ *
+ * @param caseName - The project/case name to use in the template
+ * @param description - Optional project description (defaults to "A new project")
+ * @param templatePath - Optional path to a custom template file (from settings.json)
+ * @returns The generated CLAUDE.md content
+ */
+export function generateClaudeMd(caseName, description = '', templatePath) {
+    const date = new Date().toISOString().split('T')[0];
+    // 1. Try custom template from settings.json
+    if (templatePath && existsSync(templatePath)) {
+        try {
+            const template = readFileSync(templatePath, 'utf-8');
+            return replacePlaceholders(template, caseName, description, date);
+        }
+        catch (err) {
+            console.error(`Failed to read custom template from ${templatePath}:`, err);
+        }
+    }
+    // 2. Try bundled template
+    if (existsSync(BUNDLED_TEMPLATE_PATH)) {
+        try {
+            const template = readFileSync(BUNDLED_TEMPLATE_PATH, 'utf-8');
+            return replacePlaceholders(template, caseName, description, date);
+        }
+        catch (err) {
+            console.error(`Failed to read bundled template from ${BUNDLED_TEMPLATE_PATH}:`, err);
+        }
+    }
+    // 3. Minimal fallback
+    return replacePlaceholders(MINIMAL_FALLBACK, caseName, description, date);
+}
+function replacePlaceholders(template, caseName, description, date) {
+    return template
+        .replace(/\[PROJECT_NAME\]/g, caseName)
+        .replace(/\[PROJECT_DESCRIPTION\]/g, description || 'A new project')
+        .replace(/\[DATE\]/g, date);
+}
+//# sourceMappingURL=claude-md.js.map

package/dist/templates/claude-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.js","sourceRoot":"","sources":["../../src/templates/claude-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAElE,MAAM,gBAAgB,GAAG;;;;;;;;;;;;CAYxB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,cAAsB,EAAE,EAAE,YAAqB;IAChG,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpD,4CAA4C;IAC5C,IAAI,YAAY,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACrD,OAAO,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,uCAAuC,YAAY,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI,UAAU,CAAC,qBAAqB,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,YAAY,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;YAC9D,OAAO,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,wCAAwC,qBAAqB,GAAG,EAAE,GAAG,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,OAAO,mBAAmB,CAAC,gBAAgB,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB,EAAE,QAAgB,EAAE,WAAmB,EAAE,IAAY;IAChG,OAAO,QAAQ;SACZ,OAAO,CAAC,mBAAmB,EAAE,QAAQ,CAAC;SACtC,OAAO,CAAC,0BAA0B,EAAE,WAAW,IAAI,eAAe,CAAC;SACnE,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AAChC,CAAC"}