codehere 0.3.1 → 0.3.3

package/README.md

@@ -11,48 +11,56 @@ codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks
 
 One manager, many specialists, every action recorded.
 
-## Install
+---
 
-```bash
-npm install -g codehere
-```
+## Recipe — setup to first audit in 30 minutes
 
-Requires Node.js 20+. Open-source MIT.
+> One folder convention, one prompt formula, four ready-to-use prompts.
+> Full version: **[docs/RECIPE.md](../docs/RECIPE.md)**.
 
-## Quick start
+### Setup (once)
 
-### Delegate a task to an AI agent
+| | | |
+|---|---|---|
+| 1 | **Install** | `npm install -g codehere` (Node 20+) |
+| 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
+| 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
+| 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode also supported) |
+| 5 | **Scaffold this repo** | `cd /your/repo && codehere init` — creates `.codehere/CONTEXT.md`, `HANDOVER.md`, `PROMPTS.md` |
+| 6 | **Fill in CONTEXT.md** | 5 minutes. The agent will follow what's written there. |
 
-Make sure at least one of the four supported agents is installed:
+You're done. `codehere start` opens the web UI at `:3773`; you delegate from there.
 
-| Agent | Install |
-|---|---|
-| Claude Code | `npm install -g @anthropic-ai/claude-code` |
-| Codex CLI | `npm install -g @openai/codex` |
-| Aider | `brew install aider` |
-| OpenCode | `curl -fsSL https://opencode.ai/install \| bash` |
+### The prompt formula
 
-Then:
-
-```bash
-codehere start          # opens http://127.0.0.1:3773 in your browser
 ```
+Context  +  End State  +  Constraints
+```
+
+- **Context** — *"Read .codehere/CONTEXT.md"* + any specific files
+- **End State** — the user-visible change, the test that passes, the file that exists
+- **Constraints** — files not to touch, dependencies not to add, patterns not to use
+
+### Folder convention (what `codehere init` writes)
+
+| File | Purpose | Committed? |
+|---|---|---|
+| `.codehere/CONTEXT.md` | What this repo is. Conventions. Style. Constraints. | yes |
+| `.codehere/HANDOVER.md` | Cross-session continuity (until F3 memory ships in v0.5). | **no** |
+| `.codehere/PROMPTS.md` | Your library of recurring task prompts. | yes |
 
-You'll see:
+---
 
-- **Today's activity** · "47 AI actions · 3 blocked · avg trust 91 · 4 agents"
-- **A task intake** with three starter prompts you can click
-- **A cwd field** pre-filled with where you ran `codehere start`
-- **An agent dropdown** showing which of the four are installed (and a one-click Install button for the others)
+## What you see when you delegate a task
 
-Pick an agent, type a task, hit **Assign**. codehere:
+`codehere start` opens `http://127.0.0.1:3773`. Pick an agent, type a task, hit **Assign**. codehere:
 
 1. Spawns the agent with the right headless flags
 2. Streams the steps back as readable progress · *"Read src/auth.ts · Edit src/auth.ts · Run npm test"*
 3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode tasks: emits the agent's native event stream (no per-tool blocking yet)
 4. On completion, hands you a **Final report**: files changed with `+/-` lines, trust score per file, test pass/fail, token usage
 
-Claude Code tool calls are logged to `~/.codehere/audit/hook-events.jsonl`; spawned-task lifecycle (any adapter) is logged to `~/.codehere/sessions.jsonl`.
+Claude Code tool calls are logged to `~/.codehere/audit/hook-events.jsonl`; spawned-task lifecycle (any adapter) is logged to `~/.codehere/sessions.jsonl`. Open-source MIT. Node 20+.
 
 ### Just the safety hook (no agents required)
 

package/dist/index.js

@@ -15,6 +15,7 @@ import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
+import { executeInitCommand } from './presentation/cli/commands/init-command.js';
 import { executeConfigCommand } from './presentation/cli/commands/config-command.js';
 import { executeHelpCommand } from './presentation/cli/commands/help-command.js';
 import { executeStatusCommand } from './presentation/cli/commands/status-command.js';
@@ -93,6 +94,15 @@ program
     .action(async (options) => {
     await executeSetupCommand(options.force || false);
 });
+// ── init ─────────────────────────────────────────────────────────────────────
+program
+    .command('init')
+    .description('Scaffold .codehere/ in this repo · CONTEXT, HANDOVER, PROMPTS')
+    .option('-f, --force', 'Overwrite existing files in .codehere/')
+    .option('--no-gitignore', 'Skip updating .gitignore')
+    .action((options) => {
+    executeInitCommand({ force: options.force, noGitignore: !options.gitignore });
+});
 // ── config ───────────────────────────────────────────────────────────────────
 program
     .command('config')

package/dist/presentation/cli/commands/init-command.js

@@ -0,0 +1,245 @@
+/**
+ * Init Command — scaffold a `.codehere/` directory at the repo root.
+ *
+ * The user-side analog to `git init`: gives the project a small, conventional
+ * shape codehere can read from when an agent runs here. Three files:
+ *
+ *   .codehere/CONTEXT.md   — what this repo is, conventions, constraints
+ *   .codehere/HANDOVER.md  — manual cross-session continuity (until F3 ships)
+ *   .codehere/PROMPTS.md   — your library of recurring task prompts
+ *
+ * Conventions:
+ *   - CONTEXT.md and PROMPTS.md are committed (project config, shared)
+ *   - HANDOVER.md is git-ignored by default (per-machine working state)
+ *
+ * Targets the repo root (via findCodebaseRoot), not cwd, so `cd src && codehere init`
+ * still scaffolds at the repo root, not inside src/.
+ *
+ * Idempotent: re-running detects existing files and skips them unless --force.
+ * Refuses to follow symlinks (lstat check) so a hostile/misplaced symlink at
+ * `.codehere/CONTEXT.md` or `.gitignore` cannot redirect writes outside the repo.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync, lstatSync, statSync } from 'fs';
+import { join } from 'path';
+import { colors, success, info, warning, error, newline } from '../../../ui.js';
+import { findCodebaseRoot } from '../../../domain/services/codebase-detector.js';
+const TEMPLATES = [
+    {
+        filename: 'CONTEXT.md',
+        body: `# Project Context
+
+> codehere reads this when an agent runs in this directory.
+> Keep it short. Keep it true. The agent will follow what's written here.
+
+## What this is
+
+[One-paragraph description of what this repo does and who uses it.]
+
+## Conventions
+
+[How this codebase is organized — entry points, file naming, framework version.
+Anything an agent would otherwise have to discover by grep.]
+
+## Style
+
+[Tone for generated code. Test framework. Lint rules. Imports style.
+Prefer X. Avoid Y.]
+
+## Constraints
+
+[Don't do X. Always do Y. Files that are off-limits.
+Things you've been burned by.]
+
+## Useful commands
+
+\`\`\`
+[build, test, lint, dev server — the agent will run these]
+\`\`\`
+`,
+    },
+    {
+        filename: 'HANDOVER.md',
+        body: `# Handover
+
+> Update at the end of each working session.
+> codehere has no project memory across sessions yet (F3 ships in v0.5).
+> This file is the manual handover so the next session — or the next agent —
+> can pick up without you re-explaining.
+
+## Last session
+
+- **Date:**
+- **What got done:**
+- **What's in progress:**
+- **What to pick up next:**
+- **Open questions:**
+
+## Decisions worth remembering
+
+[Decisions made this session that future sessions should respect.]
+
+## Files touched recently
+
+[List the files you've been working on. The agent can prioritize them.]
+`,
+    },
+    {
+        filename: 'PROMPTS.md',
+        body: `# Prompts
+
+> Your library of recurring task prompts.
+> Copy + adapt + delegate via \`codehere task\` or the web UI.
+>
+> The codehere prompt formula: **Context + End State + Constraints**.
+> Stack-specific details (test framework, language, file conventions) belong
+> in CONTEXT.md, not duplicated in every prompt here.
+
+## Implement a change
+
+> "Read .codehere/CONTEXT.md. [Describe the change in user-visible terms — what
+> behavior is added, removed, or changed.] Match existing conventions. Don't
+> touch unrelated files. Don't add new dependencies."
+
+## Add tests
+
+> "Read .codehere/CONTEXT.md. Add tests for [FILE / behavior]. Cover happy
+> path, edge cases, and error paths. Match the existing test style and
+> framework. Don't lower the strictness of any existing test."
+
+## Refactor safely
+
+> "Read .codehere/CONTEXT.md. Refactor [FILE / module] to [GOAL]. Keep the
+> public API stable. All existing tests must still pass. Don't introduce
+> new dependencies. Show the diff before applying."
+
+## Review changes
+
+> "Read .codehere/CONTEXT.md. Review the changes in [PR / branch / file] for:
+> security issues, missing tests, breaking changes, style violations, and
+> alignment with the constraints in CONTEXT.md. Output a short markdown
+> report; don't change any code."
+`,
+    },
+];
+const GITIGNORE_MARKER = '# Added by codehere init';
+const GITIGNORE_BLOCK = `\n${GITIGNORE_MARKER}\n.codehere/HANDOVER.md\n`;
+/**
+ * Resolve the directory to scaffold. Prefers git/package root over cwd so
+ * `cd repo/src && codehere init` still lands at repo/.
+ */
+function resolveTargetRoot() {
+    const info = findCodebaseRoot();
+    if (info)
+        return { root: info.rootPath, type: info.type };
+    return { root: process.cwd(), type: 'directory' };
+}
+/**
+ * Reject a path that exists AND is a symlink. Refusing on symlinks (rather
+ * than following) prevents an init run from clobbering files outside the
+ * repo if a hostile or misplaced symlink already exists at the target.
+ */
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function ensureGitignore(repoRoot) {
+    const gitDir = join(repoRoot, '.git');
+    if (!existsSync(gitDir))
+        return 'no-git';
+    const gitignorePath = join(repoRoot, '.gitignore');
+    if (isSymlink(gitignorePath))
+        return 'refused-symlink';
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+    if (existing.includes('.codehere/HANDOVER.md'))
+        return 'already-present';
+    appendFileSync(gitignorePath, GITIGNORE_BLOCK);
+    return 'added';
+}
+export function executeInitCommand(options = {}) {
+    try {
+        const { root, type } = resolveTargetRoot();
+        const codehereDir = join(root, '.codehere');
+        newline();
+        console.log(colors.bold('codehere init'));
+        console.log(colors.dim(`  scaffolding .codehere/ at ${type} root: ${root}`));
+        newline();
+        // Refuse if .codehere itself is a symlink — would redirect every subsequent write.
+        if (existsSync(codehereDir) && isSymlink(codehereDir)) {
+            console.log(`  ${error('refused')} .codehere is a symlink — refusing to follow. Remove it first.`);
+            newline();
+            process.exitCode = 1;
+            return;
+        }
+        if (!existsSync(codehereDir)) {
+            mkdirSync(codehereDir, { recursive: true });
+        }
+        else {
+            const codehereStat = statSync(codehereDir);
+            if (!codehereStat.isDirectory()) {
+                console.log(`  ${error('refused')} .codehere exists but is not a directory.`);
+                newline();
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const created = [];
+        const skipped = [];
+        const refused = [];
+        for (const tmpl of TEMPLATES) {
+            const target = join(codehereDir, tmpl.filename);
+            if (isSymlink(target)) {
+                refused.push(tmpl.filename);
+                continue;
+            }
+            if (existsSync(target) && !options.force) {
+                skipped.push(tmpl.filename);
+                continue;
+            }
+            writeFileSync(target, tmpl.body);
+            created.push(tmpl.filename);
+        }
+        for (const f of created) {
+            console.log(`  ${success(`created`)}  .codehere/${f}`);
+        }
+        for (const f of skipped) {
+            console.log(`  ${info(`exists `)} .codehere/${f}  ${colors.dim('(use --force to overwrite)')}`);
+        }
+        for (const f of refused) {
+            console.log(`  ${error(`refused`)} .codehere/${f}  ${colors.dim('(symlink — remove it first)')}`);
+        }
+        if (!options.noGitignore) {
+            const gitignoreResult = ensureGitignore(root);
+            newline();
+            switch (gitignoreResult) {
+                case 'added':
+                    console.log(`  ${success('updated')} .gitignore  ${colors.dim('(.codehere/HANDOVER.md ignored — per-machine working state)')}`);
+                    break;
+                case 'already-present':
+                    console.log(`  ${info('exists ')} .gitignore  ${colors.dim('(HANDOVER.md already ignored)')}`);
+                    break;
+                case 'no-git':
+                    console.log(`  ${warning('skipped')} .gitignore  ${colors.dim('(no .git directory at root)')}`);
+                    break;
+                case 'refused-symlink':
+                    console.log(`  ${error('refused')} .gitignore is a symlink — left untouched.`);
+                    break;
+            }
+        }
+        newline();
+        console.log(colors.bold('Next:'));
+        console.log(`  1. Open ${colors.cyan('.codehere/CONTEXT.md')} and fill in what this repo is`);
+        console.log(`  2. Run ${colors.cyan('codehere start')} and delegate your first task`);
+        console.log(`  3. Update ${colors.cyan('.codehere/HANDOVER.md')} at the end of the session`);
+        newline();
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`\n  ${error('failed')} codehere init — ${msg}\n`);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=init-command.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A PM for your AI coding agents. Delegate, orchestrate, and audit Claude Code, Codex, Aider, and OpenCode from one local web UI — every AI action traced, every file scored.",
   "main": "dist/index.js",
   "type": "module",