claude-project-manager 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# claude-project-manager
+
+**Turn Claude Code into an autonomous project manager.**
+
+One command. Claude plans, builds, documents, and tracks your entire project. You never write a line of code.
+
+```
+npx claude-project-manager init
+```
+
+---
+
+## What It Does
+
+`claude-project-manager` injects a structured memory system and agent rules into any project. When you open Claude Code, it behaves as a fully autonomous project manager that:
+
+- **Plans tasks** — breaks features into a kanban board and works through them
+- **Writes code** — implements everything, tests it, moves on
+- **Documents everything** — architecture diagrams, file trees, component docs, API surface
+- **Remembers across sessions** — picks up exactly where it left off
+- **Caches external docs** — checks local cache before searching the web
+- **Logs every decision** — architecture decision records with full rationale
+- **Tracks every change** — timestamped changelog, always in sync
+
+## Quick Start
+
+```bash
+# npm
+npx claude-project-manager init
+
+# pnpm
+pnpm dlx claude-project-manager init
+
+# yarn
+yarn dlx claude-project-manager init
+```
+
+Then just open Claude Code and tell it what to build:
+
+```
+"Build me a REST API with user auth and a Postgres database"
+```
+
+That's it. Claude reads the rules, scans your codebase, sets up the task board, and starts building.
+
+## What `init` Creates
+
+```
+your-project/
+├── CLAUDE.md                        # Agent rules (your existing rules preserved)
+└── .claude/
+    ├── codebase/
+    │   ├── overview.md              # Architecture + ASCII diagrams
+    │   ├── tree.md                  # Auto-updated file tree
+    │   ├── stack.md                 # Tech stack & dependencies
+    │   ├── components/              # Per-component deep dives
+    │   ├── models.md                # Data models & schemas
+    │   ├── apis.md                  # API endpoints & interfaces
+    │   └── patterns.md              # Coding conventions
+    │
+    ├── docs/
+    │   ├── index.md                 # Doc lookup table
+    │   └── cached/                  # Fetched external docs
+    │
+    ├── tasks/
+    │   ├── board.md                 # Kanban: TODO / IN PROGRESS / DONE
+    │   ├── backlog.md               # Future ideas
+    │   └── changelog.md             # Timestamped change log
+    │
+    ├── memory/
+    │   ├── decisions.md             # Architecture Decision Records
+    │   ├── context.md               # Persistent context & gotchas
+    │   └── sessions/                # Per-session summaries
+    │
+    └── config.md                    # PM settings
+```
+
+## How It Works
+
+### 1. Structured Memory
+
+Claude Code reads `CLAUDE.md` at the start of every session. `claude-project-manager` injects rules that tell Claude to use the `.claude/` folder as persistent memory — reading state on startup, writing state after every action.
+
+### 2. Session Continuity
+
+Every session ends with a summary written to `.claude/memory/sessions/`. The next session reads it and picks up where you left off. Close your terminal, come back in a week — Claude knows exactly what's happening.
+
+### 3. Auto-Updating Docs
+
+After every code change, Claude updates the file tree, component docs, architecture overview, and changelog. Your documentation is always in sync with reality.
+
+### 4. Cache-First Docs
+
+Before searching the web for library docs, Claude checks `.claude/docs/index.md`. If the docs are cached and fresh, it uses them instantly. No redundant web searches.
+
+### 5. Task Board
+
+Claude maintains a kanban board in `.claude/tasks/board.md`. It moves tasks through TODO → IN PROGRESS → DONE as it works, so you always see project status at a glance.
+
+## Existing CLAUDE.md?
+
+`claude-project-manager` never destroys your existing rules. It wraps them:
+
+```markdown
+<!-- CLAUDE-PM:USER-RULES:START -->
+(your original CLAUDE.md content — untouched)
+<!-- CLAUDE-PM:USER-RULES:END -->
+
+<!-- CLAUDE-PM:AGENT-RULES:START -->
+(project manager rules — managed by claude-project-manager)
+<!-- CLAUDE-PM:AGENT-RULES:END -->
+```
+
+Your rules stay. The PM rules are added alongside them.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `npx claude-project-manager init` | Set up project management in current directory |
+| `npx claude-project-manager reset` | Re-scaffold missing files + update agent rules to latest |
+
+### Options
+
+```
+-d, --dir <path>    Target a different directory (default: cwd)
+```
+
+### Using Other Package Managers
+
+```bash
+# pnpm
+pnpm dlx claude-project-manager init
+pnpm dlx claude-project-manager reset
+
+# yarn
+yarn dlx claude-project-manager init
+yarn dlx claude-project-manager reset
+```
+
+## Updating
+
+When a new version of `claude-project-manager` ships with improved agent rules:
+
+```bash
+# npm
+npx claude-project-manager@latest reset
+
+# pnpm
+pnpm dlx claude-project-manager@latest reset
+
+# yarn
+yarn dlx claude-project-manager@latest reset
+```
+
+This updates the agent rules to the latest version while preserving all your tasks, memory, docs, and custom rules.
+
+## Philosophy
+
+The best project management is invisible. You describe what you want in plain English. Claude plans it, builds it, documents it, and tracks it. You review the output.
+
+No tickets. No sprints. No standups. Just describe and ship.
+
+## License
+
+MIT

package/dist/claude-md.d.ts

@@ -0,0 +1,13 @@
+export interface MergeResult {
+    hadExisting: boolean;
+    userRulesPreserved: boolean;
+}
+/**
+ * Reads existing CLAUDE.md, wraps user content in markers,
+ * and injects (or updates) the PM agent rules section.
+ */
+export declare function mergeCLAUDEmd(projectRoot: string): MergeResult;
+/**
+ * Extracts the user rules section from a managed CLAUDE.md.
+ */
+export declare function extractUserRules(projectRoot: string): string | null;

package/dist/claude-md.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pmRules } from "./templates/rules.js";
+const USER_START = "<!-- CLAUDE-PM:USER-RULES:START -->";
+const USER_END = "<!-- CLAUDE-PM:USER-RULES:END -->";
+const AGENT_START = "<!-- CLAUDE-PM:AGENT-RULES:START -->";
+const AGENT_END = "<!-- CLAUDE-PM:AGENT-RULES:END -->";
+/**
+ * Reads existing CLAUDE.md, wraps user content in markers,
+ * and injects (or updates) the PM agent rules section.
+ */
+export function mergeCLAUDEmd(projectRoot) {
+    const claudePath = join(projectRoot, "CLAUDE.md");
+    const rules = pmRules();
+    // No existing file — create fresh
+    if (!existsSync(claudePath)) {
+        const content = [
+            USER_START,
+            "",
+            USER_END,
+            "",
+            AGENT_START,
+            rules,
+            AGENT_END,
+            "",
+        ].join("\n");
+        writeFileSync(claudePath, content, "utf-8");
+        return { hadExisting: false, userRulesPreserved: false };
+    }
+    // Existing file — read and merge
+    const existing = readFileSync(claudePath, "utf-8");
+    // Already managed by claude-pm — update agent rules only
+    if (existing.includes(AGENT_START)) {
+        const before = existing.substring(0, existing.indexOf(AGENT_START) + AGENT_START.length);
+        const after = existing.substring(existing.indexOf(AGENT_END));
+        const updated = before + "\n" + rules + "\n" + after;
+        writeFileSync(claudePath, updated, "utf-8");
+        return { hadExisting: true, userRulesPreserved: true };
+    }
+    // Existing file not yet managed — wrap user content, append agent rules
+    const content = [
+        USER_START,
+        existing.trim(),
+        USER_END,
+        "",
+        AGENT_START,
+        rules,
+        AGENT_END,
+        "",
+    ].join("\n");
+    writeFileSync(claudePath, content, "utf-8");
+    return { hadExisting: true, userRulesPreserved: true };
+}
+/**
+ * Extracts the user rules section from a managed CLAUDE.md.
+ */
+export function extractUserRules(projectRoot) {
+    const claudePath = join(projectRoot, "CLAUDE.md");
+    if (!existsSync(claudePath))
+        return null;
+    const content = readFileSync(claudePath, "utf-8");
+    if (!content.includes(USER_START) || !content.includes(USER_END)) {
+        return null;
+    }
+    const start = content.indexOf(USER_START) + USER_START.length;
+    const end = content.indexOf(USER_END);
+    return content.substring(start, end).trim();
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { runInit } from "./commands/init.js";
+import { runReset } from "./commands/reset.js";
+import { bold, dim } from "./utils.js";
+const program = new Command();
+program
+    .name("claude-project-manager")
+    .description("Turn Claude Code into an autonomous project manager")
+    .version("1.0.0");
+program
+    .command("init")
+    .description("Initialize project management in the current directory")
+    .option("-d, --dir <path>", "Target directory (default: current directory)")
+    .action((opts) => {
+    const targetDir = resolve(opts.dir ?? process.cwd());
+    runInit(targetDir);
+});
+program
+    .command("reset")
+    .description("Re-scaffold missing files and update agent rules to latest version")
+    .option("-d, --dir <path>", "Target directory (default: current directory)")
+    .action((opts) => {
+    const targetDir = resolve(opts.dir ?? process.cwd());
+    runReset(targetDir);
+});
+// Default: show help with branding
+program.addHelpText("beforeAll", () => {
+    return [
+        "",
+        bold("  claude-project-manager") + dim(" — autonomous project management for Claude Code"),
+        "",
+    ].join("\n");
+});
+program.parse();

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(targetDir: string): void;

package/dist/commands/init.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { scaffoldDotClaude } from "../scaffold.js";
+import { mergeCLAUDEmd } from "../claude-md.js";
+import { bold, green, cyan, yellow, dim } from "../utils.js";
+export function runInit(targetDir) {
+    const projectName = basename(targetDir);
+    console.log("");
+    console.log(bold("  claude-project-manager init"));
+    console.log(dim(`  Project: ${projectName}`));
+    console.log(dim(`  Path:    ${targetDir}`));
+    console.log("");
+    // Step 1: Scaffold .claude/ directory
+    const dotClaudeExists = existsSync(join(targetDir, ".claude"));
+    console.log(dotClaudeExists
+        ? yellow("  .claude/ directory exists — preserving existing files")
+        : green("  Creating .claude/ directory structure..."));
+    const { created, skipped } = scaffoldDotClaude(targetDir);
+    for (const file of created) {
+        console.log(green(`    + ${file}`));
+    }
+    for (const file of skipped) {
+        console.log(dim(`    ~ ${file} (already exists, skipped)`));
+    }
+    console.log("");
+    // Step 2: Merge CLAUDE.md
+    const claudeExists = existsSync(join(targetDir, "CLAUDE.md"));
+    if (claudeExists) {
+        console.log(yellow("  CLAUDE.md exists — preserving your rules, injecting PM agent rules"));
+    }
+    else {
+        console.log(green("  Creating CLAUDE.md with PM agent rules..."));
+    }
+    const mergeResult = mergeCLAUDEmd(targetDir);
+    if (mergeResult.hadExisting && mergeResult.userRulesPreserved) {
+        console.log(green("    Your existing rules are preserved in the USER-RULES section"));
+    }
+    console.log(green("    PM agent rules injected into AGENT-RULES section"));
+    // Done
+    console.log("");
+    console.log(bold(green("  Done! Claude is now your project manager.")));
+    console.log("");
+    console.log("  What happened:");
+    console.log(cyan("    .claude/codebase/") + "  — Architecture docs, file tree, component maps");
+    console.log(cyan("    .claude/docs/") + "      — Cached external documentation");
+    console.log(cyan("    .claude/tasks/") + "     — Task board, backlog, changelog");
+    console.log(cyan("    .claude/memory/") + "    — Decisions, context, session history");
+    console.log(cyan("    CLAUDE.md") + "          — Agent rules (your rules preserved)");
+    console.log("");
+    console.log("  Next steps:");
+    console.log(dim("    1. Open Claude Code in this project"));
+    console.log(dim('    2. Tell it what to build: "Build me a REST API with auth"'));
+    console.log(dim("    3. Watch it plan, build, and track everything autonomously"));
+    console.log("");
+}

package/dist/commands/reset.d.ts

@@ -0,0 +1 @@
+export declare function runReset(targetDir: string): void;

package/dist/commands/reset.js

@@ -0,0 +1,38 @@
+import { basename } from "node:path";
+import { scaffoldDotClaude } from "../scaffold.js";
+import { mergeCLAUDEmd, extractUserRules } from "../claude-md.js";
+import { bold, green, yellow, dim } from "../utils.js";
+export function runReset(targetDir) {
+    const projectName = basename(targetDir);
+    console.log("");
+    console.log(bold("  claude-project-manager reset"));
+    console.log(dim(`  Project: ${projectName}`));
+    console.log("");
+    // Preserve user rules
+    const userRules = extractUserRules(targetDir);
+    if (userRules) {
+        console.log(green("  User rules found and preserved"));
+    }
+    // Re-scaffold (writeIfMissing means existing files won't be overwritten)
+    console.log(yellow("  Re-scaffolding .claude/ structure..."));
+    const { created, skipped } = scaffoldDotClaude(targetDir);
+    for (const file of created) {
+        console.log(green(`    + ${file}`));
+    }
+    for (const file of skipped) {
+        console.log(dim(`    ~ ${file} (preserved)`));
+    }
+    console.log("");
+    // Re-inject latest rules
+    console.log(yellow("  Updating PM agent rules in CLAUDE.md..."));
+    mergeCLAUDEmd(targetDir);
+    console.log(green("    Agent rules updated to latest version"));
+    if (userRules) {
+        console.log(green("    Your custom rules are untouched"));
+    }
+    console.log("");
+    console.log(bold(green("  Reset complete.")));
+    console.log(dim("  Existing task data, memory, and docs were preserved."));
+    console.log(dim("  Only missing scaffold files were recreated and agent rules updated."));
+    console.log("");
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,5 @@
+export interface ScaffoldResult {
+    created: string[];
+    skipped: string[];
+}
+export declare function scaffoldDotClaude(projectRoot: string): ScaffoldResult;

package/dist/scaffold.js

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import { ensureDir, writeIfMissing } from "./utils.js";
+import { defaultBoard, defaultBacklog, defaultChangelog, defaultConfig, defaultOverview, defaultTree, defaultStack, defaultModels, defaultApis, defaultPatterns, defaultDocsIndex, defaultDecisions, defaultContext, } from "./templates/defaults.js";
+export function scaffoldDotClaude(projectRoot) {
+    const base = join(projectRoot, ".claude");
+    const created = [];
+    const skipped = [];
+    // Create all directories
+    const dirs = [
+        join(base, "codebase", "components"),
+        join(base, "docs", "cached"),
+        join(base, "tasks"),
+        join(base, "memory", "sessions"),
+    ];
+    for (const dir of dirs) {
+        ensureDir(dir);
+    }
+    // Write template files (skip if they already exist to preserve user data)
+    const files = [
+        // Codebase
+        [join(base, "codebase", "overview.md"), defaultOverview],
+        [join(base, "codebase", "tree.md"), defaultTree],
+        [join(base, "codebase", "stack.md"), defaultStack],
+        [join(base, "codebase", "models.md"), defaultModels],
+        [join(base, "codebase", "apis.md"), defaultApis],
+        [join(base, "codebase", "patterns.md"), defaultPatterns],
+        // Docs
+        [join(base, "docs", "index.md"), defaultDocsIndex],
+        // Tasks
+        [join(base, "tasks", "board.md"), defaultBoard],
+        [join(base, "tasks", "backlog.md"), defaultBacklog],
+        [join(base, "tasks", "changelog.md"), defaultChangelog],
+        // Memory
+        [join(base, "memory", "decisions.md"), defaultDecisions],
+        [join(base, "memory", "context.md"), defaultContext],
+        // Config
+        [join(base, "config.md"), defaultConfig],
+    ];
+    for (const [filePath, content] of files) {
+        const wasCreated = writeIfMissing(filePath, content);
+        const relative = filePath.replace(projectRoot + "/", "");
+        if (wasCreated) {
+            created.push(relative);
+        }
+        else {
+            skipped.push(relative);
+        }
+    }
+    return { created, skipped };
+}

package/dist/templates/defaults.d.ts

@@ -0,0 +1,13 @@
+export declare const defaultBoard = "# Task Board\n\n## TODO\n<!-- Add tasks here as: - [ ] #N \u2014 Task description -->\n\n## IN PROGRESS\n\n## DONE\n";
+export declare const defaultBacklog = "# Backlog\n\nIdeas, future features, and low-priority items.\n\n<!-- Add items here as bullet points -->\n";
+export declare const defaultChangelog = "# Changelog\n\nTimestamped log of all changes made to the project.\n\n<!-- Entries are added automatically by the project manager -->\n";
+export declare const defaultOverview = "# Architecture Overview\n\n<!-- This file is auto-maintained by the project manager. -->\n<!-- It contains the high-level system design and ASCII diagrams. -->\n\n## System Architecture\n\n> Pending initial codebase analysis.\n\n## Data Flow\n\n> Pending initial codebase analysis.\n";
+export declare const defaultTree = "# Project File Tree\n\n<!-- This file is auto-maintained by the project manager. -->\n<!-- Regenerated whenever files are added, removed, or moved. -->\n\n> Pending initial codebase scan.\n";
+export declare const defaultStack = "# Tech Stack\n\n<!-- This file is auto-maintained by the project manager. -->\n\n## Frameworks & Libraries\n\n> Pending initial codebase analysis.\n\n## Dev Dependencies\n\n> Pending initial codebase analysis.\n\n## Infrastructure\n\n> Pending initial codebase analysis.\n";
+export declare const defaultModels = "# Data Models\n\n<!-- This file is auto-maintained by the project manager. -->\n<!-- All database schemas, types, and data structures. -->\n\n> Pending initial codebase analysis.\n";
+export declare const defaultApis = "# API Surface\n\n<!-- This file is auto-maintained by the project manager. -->\n<!-- All endpoints, routes, and interfaces. -->\n\n> Pending initial codebase analysis.\n";
+export declare const defaultPatterns = "# Patterns & Conventions\n\n<!-- This file is auto-maintained by the project manager. -->\n<!-- Coding conventions, naming rules, and established patterns. -->\n\n> Pending initial codebase analysis.\n";
+export declare const defaultDocsIndex = "# Documentation Index\n\nCached external documentation for this project.\n\n| Name | Source URL | Date Cached | File |\n|------|-----------|-------------|------|\n<!-- Entries are added automatically when docs are fetched -->\n";
+export declare const defaultDecisions = "# Architecture Decision Records\n\nSignificant technical decisions and their rationale.\n\n<!-- Entries are added automatically by the project manager -->\n";
+export declare const defaultContext = "# Persistent Context\n\nKey facts, preferences, and gotchas that should persist across sessions.\n\n## User Preferences\n\n<!-- e.g., preferred frameworks, coding style, etc. -->\n\n## Environment\n\n<!-- e.g., OS, Node version, special setup requirements -->\n\n## Known Gotchas\n\n<!-- Things that broke before and how they were fixed -->\n";
+export declare const defaultConfig = "# Project Manager Configuration\n\n## Project\n- **Name:** (auto-detected)\n- **Type:** (auto-detected)\n\n## Settings\n- **Auto-update docs:** true\n- **Doc cache max age (days):** 30\n- **Session summaries:** true\n";

package/dist/templates/defaults.js

@@ -0,0 +1,124 @@
+// ─── Tasks ───────────────────────────────────────────────────────────
+export const defaultBoard = `# Task Board
+
+## TODO
+<!-- Add tasks here as: - [ ] #N — Task description -->
+
+## IN PROGRESS
+
+## DONE
+`;
+export const defaultBacklog = `# Backlog
+
+Ideas, future features, and low-priority items.
+
+<!-- Add items here as bullet points -->
+`;
+export const defaultChangelog = `# Changelog
+
+Timestamped log of all changes made to the project.
+
+<!-- Entries are added automatically by the project manager -->
+`;
+// ─── Codebase ────────────────────────────────────────────────────────
+export const defaultOverview = `# Architecture Overview
+
+<!-- This file is auto-maintained by the project manager. -->
+<!-- It contains the high-level system design and ASCII diagrams. -->
+
+## System Architecture
+
+> Pending initial codebase analysis.
+
+## Data Flow
+
+> Pending initial codebase analysis.
+`;
+export const defaultTree = `# Project File Tree
+
+<!-- This file is auto-maintained by the project manager. -->
+<!-- Regenerated whenever files are added, removed, or moved. -->
+
+> Pending initial codebase scan.
+`;
+export const defaultStack = `# Tech Stack
+
+<!-- This file is auto-maintained by the project manager. -->
+
+## Frameworks & Libraries
+
+> Pending initial codebase analysis.
+
+## Dev Dependencies
+
+> Pending initial codebase analysis.
+
+## Infrastructure
+
+> Pending initial codebase analysis.
+`;
+export const defaultModels = `# Data Models
+
+<!-- This file is auto-maintained by the project manager. -->
+<!-- All database schemas, types, and data structures. -->
+
+> Pending initial codebase analysis.
+`;
+export const defaultApis = `# API Surface
+
+<!-- This file is auto-maintained by the project manager. -->
+<!-- All endpoints, routes, and interfaces. -->
+
+> Pending initial codebase analysis.
+`;
+export const defaultPatterns = `# Patterns & Conventions
+
+<!-- This file is auto-maintained by the project manager. -->
+<!-- Coding conventions, naming rules, and established patterns. -->
+
+> Pending initial codebase analysis.
+`;
+// ─── Docs ────────────────────────────────────────────────────────────
+export const defaultDocsIndex = `# Documentation Index
+
+Cached external documentation for this project.
+
+| Name | Source URL | Date Cached | File |
+|------|-----------|-------------|------|
+<!-- Entries are added automatically when docs are fetched -->
+`;
+// ─── Memory ──────────────────────────────────────────────────────────
+export const defaultDecisions = `# Architecture Decision Records
+
+Significant technical decisions and their rationale.
+
+<!-- Entries are added automatically by the project manager -->
+`;
+export const defaultContext = `# Persistent Context
+
+Key facts, preferences, and gotchas that should persist across sessions.
+
+## User Preferences
+
+<!-- e.g., preferred frameworks, coding style, etc. -->
+
+## Environment
+
+<!-- e.g., OS, Node version, special setup requirements -->
+
+## Known Gotchas
+
+<!-- Things that broke before and how they were fixed -->
+`;
+// ─── Config ──────────────────────────────────────────────────────────
+export const defaultConfig = `# Project Manager Configuration
+
+## Project
+- **Name:** (auto-detected)
+- **Type:** (auto-detected)
+
+## Settings
+- **Auto-update docs:** true
+- **Doc cache max age (days):** 30
+- **Session summaries:** true
+`;

package/dist/templates/rules.d.ts

@@ -0,0 +1 @@
+export declare function pmRules(): string;

package/dist/templates/rules.js

@@ -0,0 +1,184 @@
+export function pmRules() {
+    return `
+# Claude Project Manager — Agent Rules
+
+You are an **autonomous project manager**. You fully manage this project — planning, building, documenting, and tracking everything. The user should never need to write code themselves.
+
+---
+
+## Session Startup Protocol
+
+On EVERY new conversation or session:
+
+1. Read \`.claude/tasks/board.md\` to understand current project state
+2. Read the latest file in \`.claude/memory/sessions/\` to restore context from the last session
+3. Read \`.claude/memory/context.md\` for persistent knowledge (preferences, gotchas, env quirks)
+4. Briefly summarize current state to the user:
+   - What was completed last session
+   - What's currently in progress
+   - What's next on the board
+5. Ask the user what they'd like to focus on, or propose continuing with the next TODO task
+
+---
+
+## Task Management
+
+### Task Board — \`.claude/tasks/board.md\`
+
+Maintain a kanban board with three columns: **TODO**, **IN PROGRESS**, **DONE**.
+
+Format:
+\`\`\`markdown
+## TODO
+- [ ] #4 — Add user authentication
+- [ ] #5 — Set up CI/CD pipeline
+
+## IN PROGRESS
+- [ ] #3 — Build REST API endpoints (started: 2025-01-15)
+
+## DONE
+- [x] #1 — Initialize project structure (completed: 2025-01-14)
+- [x] #2 — Set up database schema (completed: 2025-01-14)
+\`\`\`
+
+Rules:
+- Every task gets a unique ID (#N, incrementing)
+- BEFORE starting any coding work, move the relevant task to IN PROGRESS
+- AFTER completing work, move the task to DONE with the completion date
+- When the user describes a new feature or request, break it into small specific tasks and add to TODO
+- One task = one logical unit of work (completable in a single session ideally)
+
+### Backlog — \`.claude/tasks/backlog.md\`
+- Store future ideas, nice-to-haves, and low-priority items
+- Periodically ask the user if any backlog items should be promoted to TODO
+
+### Changelog — \`.claude/tasks/changelog.md\`
+- After EVERY code change, append an entry with the date, what changed, files affected, and which task it relates to
+- This is **append-only** — never delete or modify past entries
+- Format:
+\`\`\`markdown
+## 2025-01-15
+- Built REST API scaffolding — src/api/routes.ts, src/api/controllers/ (#3)
+- Added Express + TypeScript base configuration (#3)
+\`\`\`
+
+---
+
+## Codebase Documentation
+
+### Auto-Update Rule
+After EVERY code change, check if any of the following need updating. If they do, update them immediately:
+
+1. **File Tree** — \`.claude/codebase/tree.md\`
+   - Regenerate when files/folders are added, removed, or moved
+   - Annotate key directories with their purpose
+   - Keep it accurate — this is the first thing you'll read to understand the project
+
+2. **Architecture Overview** — \`.claude/codebase/overview.md\`
+   - High-level system design with ASCII flow diagrams
+   - Show how major components connect and data flows between them
+   - Update when new systems, services, or major modules are added
+
+3. **Component Docs** — \`.claude/codebase/components/<name>.md\`
+   - One markdown file per major component, module, or service
+   - Each file includes: purpose, key files, dependencies, public interface, known edge cases
+   - Create a new component doc when introducing a new module
+   - Update when a component's behavior or interface changes
+
+4. **Tech Stack** — \`.claude/codebase/stack.md\`
+   - All frameworks, libraries, and tools with their versions
+   - Update when dependencies are added, removed, or upgraded
+
+5. **Data Models** — \`.claude/codebase/models.md\`
+   - All database schemas, TypeScript types/interfaces, data structures
+   - Update when models or schemas change
+
+6. **API Surface** — \`.claude/codebase/apis.md\`
+   - All API endpoints, routes, WebSocket events, or other interfaces
+   - Include: method, path, params, request/response shape
+   - Update when APIs are added or modified
+
+7. **Patterns & Conventions** — \`.claude/codebase/patterns.md\`
+   - Coding conventions, naming patterns, file organization rules, error handling approach
+   - Update when new conventions are established
+
+---
+
+## External Documentation
+
+### Cache-First Strategy
+
+BEFORE searching the web for any library, framework, or API documentation:
+1. Check \`.claude/docs/index.md\` for a cached version
+2. If found and less than 30 days old → use the cached version
+3. If found but older than 30 days → re-fetch, update cache, update index
+4. If not found → fetch, save to \`.claude/docs/cached/<name>.md\`, add to index
+
+### Index Format — \`.claude/docs/index.md\`
+\`\`\`markdown
+| Name | Source URL | Date Cached | File |
+|------|-----------|-------------|------|
+| Next.js App Router | https://nextjs.org/docs/app | 2025-01-15 | nextjs-app-router.md |
+\`\`\`
+
+### Caching Rules
+- Only cache what's relevant to this project — summarize large docs
+- Store in \`.claude/docs/cached/<library-name>.md\`
+- Include the source URL and cache date at the top of each cached file
+
+---
+
+## Memory & Context
+
+### Persistent Context — \`.claude/memory/context.md\`
+- Key facts the agent should always know: user preferences, environment details, recurring gotchas, things that broke before and how they were fixed
+- Update whenever you discover something future sessions should know
+- Format as categorized bullet points
+
+### Architecture Decisions — \`.claude/memory/decisions.md\`
+Log every significant technical decision using this format:
+\`\`\`markdown
+### Decision: [Title]
+**Date:** YYYY-MM-DD
+**Context:** Why this decision came up
+**Decision:** What was chosen
+**Alternatives:** What else was considered
+**Rationale:** Why this option won
+\`\`\`
+
+Rules:
+- NEVER re-debate a logged decision unless the user explicitly asks to revisit it
+- Reference past decisions when they're relevant to current work
+
+### Session Summaries — \`.claude/memory/sessions/\`
+At the end of each session or when the conversation is wrapping up:
+- Create or append to \`.claude/memory/sessions/YYYY-MM-DD.md\`
+- Include: tasks completed, tasks in progress, blockers encountered, what to do next
+- This is how the next session picks up where you left off
+
+---
+
+## Autonomous Behavior
+
+You are **fully autonomous**. Plan, build, test, and document without waiting for step-by-step approval.
+
+**Only ask the user for input when:**
+- A major architecture decision is needed (new framework, database choice, deployment strategy)
+- Requirements are ambiguous (you genuinely don't know what the user wants)
+- A destructive operation is proposed (deleting features, major breaking refactors)
+
+**For everything else:** decide, execute, document, and report what you did after.
+
+**After completing any task:**
+1. Update the task board (move to DONE)
+2. Update the changelog
+3. Update any affected codebase docs (tree, components, etc.)
+4. Briefly tell the user what was done and what's next
+
+---
+
+## Project Configuration
+
+Settings are in \`.claude/config.md\`. Respect any user-defined overrides found there.
+`.trim();
+}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+export declare const bold: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare function ensureDir(dirPath: string): void;
+export declare function writeIfMissing(filePath: string, content: string): boolean;
+export declare function writeAlways(filePath: string, content: string): void;

package/dist/utils.js

@@ -0,0 +1,26 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+// ANSI color helpers — zero dependencies
+export const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+export const green = (s) => `\x1b[32m${s}\x1b[0m`;
+export const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+export const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+export const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+export const red = (s) => `\x1b[31m${s}\x1b[0m`;
+export function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+export function writeIfMissing(filePath, content) {
+    ensureDir(dirname(filePath));
+    if (existsSync(filePath)) {
+        return false;
+    }
+    writeFileSync(filePath, content, "utf-8");
+    return true;
+}
+export function writeAlways(filePath, content) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, content, "utf-8");
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-project-manager",
+  "version": "1.0.0",
+  "description": "Turn Claude Code into an autonomous project manager. Zero-code project management with persistent memory, auto-updating docs, and full task tracking.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "project-manager",
+    "ai",
+    "agent",
+    "autonomous",
+    "coding-agent",
+    "claude-md",
+    "anthropic"
+  ],
+  "author": "Blox Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mehrang0/claude-project-manager"
+  },
+  "type": "module",
+  "bin": {
+    "claude-project-manager": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}