codiedev 0.3.2 → 0.3.4

package/dist/cli.js

@@ -25,6 +25,10 @@ const promote_1 = require("./commands/promote");
 const HELP = `
 CodieDev CLI
 
+  The team artifact layer for agent-coded work. Share specs and reviews
+  with teammates, get pinged when they need your input, pick up where
+  someone left off across sessions and providers.
+
 Connect:
   codiedev connect                       Link Claude Code / Codex to your org
 
@@ -45,19 +49,260 @@ Capture:
   codiedev note "<text>"                 Capture a passing thought
 
 Other:
-  codiedev help                          Show this help
+  codiedev help [command]                Show this help, or details for one command
+  codiedev docs                          Print the full usage guide
   codiedev version                       Show version
 
+Filename conventions:
+  spec-*.md      → spec          review-*.md    → review
+  decision-*.md  → decision      proposal-*.md  → proposal
+  bugfix-*.md    → bugfix        anything else  → note
+
+Examples:
+  codiedev push docs/specs/spec-cart-clear.md
+  codiedev pull spec-cart-clear.md
+  codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+  codiedev inbox --unread
+  codiedev note "idempotency key is worth a follow-up"
+
 Backend: ${process.env.CODIEDEV_URL ?? "https://codiedev.com"}
+Token:   https://codiedev.com/portal/integrations/claude-code
+Docs:    codiedev docs
+`.trim();
+const COMMAND_HELP = {
+    connect: `
+codiedev connect — link your agent CLI to CodieDev
+
+  Interactive setup. Prompts for an API token, then installs:
+    - ~/.codiedev/config.json            (token + org + tracked repos)
+    - ~/.claude/settings.json hook       (captures session transcripts)
+    - ~/.claude/CLAUDE.md instructions   (teaches Claude the commands)
+    - ~/.codex/hooks.json hook           (same, for Codex)
+    - ~/.codex/AGENTS.md instructions    (same, for Codex)
+
+  Re-run anytime to swap accounts or refresh the instruction block.
+
+  Get your token: https://codiedev.com/portal/integrations/claude-code
+`.trim(),
+    push: `
+codiedev push — author or update an artifact
+
+  Usage:
+    codiedev push <file.md> [--type spec|review|decision|proposal|bugfix|note]
+
+  The file's basename becomes its key (unique per company). Pushing the
+  same key again creates a new version — full history is preserved.
+
+  Type is inferred from the filename prefix unless you override with --type.
+
+  Examples:
+    codiedev push spec-cart-clear.md
+    codiedev push docs/review-auth.md --type review
+    codiedev push notes/random.md --type note
+`.trim(),
+    pull: `
+codiedev pull — fetch an artifact
+
+  Usage:
+    codiedev pull <key> [--version N] [--out path.md]
+
+  By default prints to stdout (pipe-friendly). --out writes to a file.
+  --version gets a specific historical version; omit for the latest.
+
+  Examples:
+    codiedev pull spec-cart-clear.md
+    codiedev pull spec-cart-clear.md --version 2
+    codiedev pull spec-cart-clear.md --out ./local-copy.md
+    codiedev pull spec-cart-clear.md | less
+`.trim(),
+    ping: `
+codiedev ping — send a teammate a message, optionally attached to an artifact
+
+  Usage:
+    codiedev ping <user> "<message>" [--with <artifact-key>]
+
+  <user> resolves to a teammate in your org by first name, full name,
+  or email. Ambiguous matches return a list — retry with the full email.
+
+  Teammates are notified by email and can reply from their own agent.
+
+  Examples:
+    codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+    codiedev ping nic@signalandcode.co "can you take this one?"
+`.trim(),
+    inbox: `
+codiedev inbox — show messages from teammates
+
+  Usage:
+    codiedev inbox [--unread] [--limit N]
+
+  Lists pings with sender, subject artifact, and preview. Each row
+  shows a ping-id you can pass to 'codiedev read'.
+
+  Unread rows show as ● ; read rows as · .
+
+  Examples:
+    codiedev inbox
+    codiedev inbox --unread
+    codiedev inbox --limit 10
+`.trim(),
+    read: `
+codiedev read — mark a ping as read and show its full content
+
+  Usage:
+    codiedev read <ping-id>
+
+  Grab the ping-id from 'codiedev inbox'. After reading, the ping will
+  drop out of 'codiedev inbox --unread' and the portal inbox badge
+  decrements for you.
+`.trim(),
+    note: `
+codiedev note — capture a passing thought, linked to your session
+
+  Usage:
+    codiedev note "<text>"
+
+  Stores the note in your org memory so you can search it later or
+  reference it in a ticket. Notes appear in the portal under the
+  Agent Inbox → My authored artifacts.
+
+  Examples:
+    codiedev note "idempotency key is worth a follow-up"
+    codiedev note "timeout threshold feels arbitrary — validate on slow networks"
+`.trim(),
+    promote: `
+codiedev promote — promote an auto-extracted artifact to authored
+
+  Usage:
+    codiedev promote <artifact-id> [--key filename.md]
+
+  The session-capture pipeline auto-extracts spec/bugfix/decision
+  artifacts from each agent session. Promote turns one of those into
+  a first-class authored artifact your team can ping, pull, and
+  update versions of.
+
+  Find artifact-ids in the portal under Knowledge → Memory, or via
+  the portal search.
+`.trim(),
+};
+const DOCS = `
+CodieDev — usage guide
+
+## What this is
+
+CodieDev is a team artifact layer on top of your coding agent (Claude
+Code, Codex, etc.). It persists the *durable* outputs of agent work —
+specs, reviews, decisions, proposals, and captured thoughts — so:
+
+  - Your teammates can pick up where you left off without a handoff call.
+  - Your manager can see what's shipping and why, grounded in real
+    session evidence.
+  - Your future self can search "what did we decide about X?" and get
+    a real answer with citations.
+
+## Core loop
+
+  1. You push an artifact:
+       codiedev push spec-cart-clear.md
+
+  2. Your teammate gets pinged (either directly by you, or because
+     they asked to be kept in the loop on that key):
+       codiedev ping maya "thoughts?" --with spec-cart-clear.md
+
+  3. They check their inbox:
+       codiedev inbox
+
+  4. They pull your artifact, edit it, and push back:
+       codiedev pull spec-cart-clear.md > my-copy.md
+       # ...edit...
+       codiedev push my-copy.md   (saves as v2 of the same key)
+
+  5. You pull the updated version and keep building.
+
+## Versions
+
+Every push of the same filename creates a new version. Latest is the
+default on pull; use --version N to get a historical one. All versions
+are preserved — you can always roll back.
+
+## Lifecycle
+
+Artifacts have a status that auto-advances as PRs reference them:
+
+  draft  →  accepted  →  implementing  →  shipped
+                                       →  archived
+
+Artifacts stay editable at every stage, including after merge —
+lessons-learned and follow-up notes append as new versions.
+
+## Portal
+
+Everything you do in the CLI is visible at:
+
+    https://codiedev.com/portal/inbox
+
+Your CTO (or any non-technical teammate) can follow along without ever
+touching a terminal — they read the artifacts in the portal and get
+email notifications when pinged.
+
+## Agent-native
+
+If you use Claude Code or Codex, the agent already knows the commands —
+'codiedev connect' installs instructions into your user-level config.
+Just say things like:
+
+    "push this spec and ping Nic"
+    "any messages?"
+    "pull Maya's latest spec"
+
+The agent will run the right command via Bash.
+
+## Command reference
+
+Run 'codiedev help <command>' for each, or see the quick list:
+
+    codiedev help
+
+## Getting a token
+
+  1. Log in to https://codiedev.com/portal/integrations/claude-code
+  2. Click "Create token"
+  3. Copy the cdv_... string and paste it into 'codiedev connect'
+
+Tokens are per-user. Rotate any time by revoking + creating a new one.
 `.trim();
 async function main() {
     const [, , command, ...rest] = process.argv;
-    if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (!command || command === "--help" || command === "-h") {
         console.log(HELP);
         return;
     }
+    if (command === "help") {
+        const sub = rest[0];
+        if (sub && COMMAND_HELP[sub]) {
+            console.log(COMMAND_HELP[sub]);
+            return;
+        }
+        if (sub) {
+            console.log(`No help for "${sub}". Valid commands:`);
+            console.log(Object.keys(COMMAND_HELP).join(", "));
+            return;
+        }
+        console.log(HELP);
+        return;
+    }
+    if (command === "docs") {
+        console.log(DOCS);
+        return;
+    }
+    // Support `codiedev <command> --help` too.
+    if (rest.includes("--help") || rest.includes("-h")) {
+        if (COMMAND_HELP[command]) {
+            console.log(COMMAND_HELP[command]);
+            return;
+        }
+    }
     if (command === "version" || command === "--version" || command === "-v") {
-        // Package version is replaced at publish via tsc — for now, print the source-of-truth.
         console.log("codiedev cli");
         return;
     }

package/dist/connect.js

@@ -150,6 +150,13 @@ async function runConnect() {
         catch (err) {
             console.error(`\nWarning: Failed to install Claude Code hook — ${err.message}`);
         }
+        try {
+            (0, utils_1.installClaudeCodeInstructions)();
+            installed.push("Claude Code agent instructions (~/.claude/CLAUDE.md)");
+        }
+        catch (err) {
+            console.error(`\nWarning: Failed to install Claude Code instructions — ${err.message}`);
+        }
     }
     if (hasCodex) {
         try {
@@ -159,6 +166,13 @@ async function runConnect() {
         catch (err) {
             console.error(`\nWarning: Failed to install Codex hook — ${err.message}`);
         }
+        try {
+            (0, utils_1.installCodexInstructions)();
+            installed.push("Codex agent instructions (~/.codex/AGENTS.md)");
+        }
+        catch (err) {
+            console.error(`\nWarning: Failed to install Codex instructions — ${err.message}`);
+        }
     }
     if (!hasClaude && !hasCodex) {
         console.warn("\nNo Claude Code (~/.claude) or Codex (~/.codex) install detected.");

package/dist/utils.d.ts

@@ -27,6 +27,8 @@ export declare function hashToken(token: string): string;
 export declare function claudeCodeInstalled(): boolean;
 export declare function codexInstalled(): boolean;
 export declare function installHook(): void;
+export declare function installClaudeCodeInstructions(): void;
+export declare function installCodexInstructions(): void;
 /**
  * Install the CodieDev MCP server into Claude Code's user-scope config.
  * Safe to call multiple times — updates the existing entry if present.

package/dist/utils.js

@@ -42,6 +42,8 @@ exports.hashToken = hashToken;
 exports.claudeCodeInstalled = claudeCodeInstalled;
 exports.codexInstalled = codexInstalled;
 exports.installHook = installHook;
+exports.installClaudeCodeInstructions = installClaudeCodeInstructions;
+exports.installCodexInstructions = installCodexInstructions;
 exports.installClaudeCodeMcp = installClaudeCodeMcp;
 exports.installCodexMcp = installCodexMcp;
 exports.installCodexHook = installCodexHook;
@@ -189,7 +191,94 @@ function installHook() {
 // agent CLI's expected location so "npx codiedev connect" wires it up once.
 // ─────────────────────────────────────────────────────────────────────────────
 const CLAUDE_USER_CONFIG_PATH = path.join(os.homedir(), ".claude.json");
+const CLAUDE_USER_INSTRUCTIONS_PATH = path.join(os.homedir(), ".claude", "CLAUDE.md");
+const CODEX_USER_INSTRUCTIONS_PATH = path.join(os.homedir(), ".codex", "AGENTS.md");
 const CODEX_CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
+const CODIEDEV_INSTRUCTIONS_BEGIN = "<!-- codiedev-cli:begin -->";
+const CODIEDEV_INSTRUCTIONS_END = "<!-- codiedev-cli:end -->";
+const CODIEDEV_INSTRUCTIONS_BODY = `## CodieDev — team artifact layer
+
+This machine is connected to CodieDev. Teammates share specs, reviews,
+decisions, and messages via a CLI on every dev's machine.
+
+**When the user asks to share, push, ping, check messages, or capture a
+thought, use the \`codiedev\` CLI via Bash:**
+
+| Intent | Command |
+|---|---|
+| "push this spec" / "share this with the team" | \`codiedev push <file.md>\` |
+| "pull X" / "grab the latest spec-X" / "what did Maya push?" | \`codiedev pull <key>\` |
+| "ping Nic about this" / "ask Maya for her take" | \`codiedev ping <name> "<msg>" [--with <key>]\` |
+| "any messages?" / "check my inbox" / "what did Nic say?" | \`codiedev inbox\` |
+| "read Nic's reply" / "mark that ping read" | \`codiedev read <ping-id>\` |
+| "note that X is a follow-up" / "remember X" | \`codiedev note "<text>"\` |
+| "promote the extracted spec" | \`codiedev promote <artifact-id>\` |
+
+**Filename conventions (set artifact type automatically):**
+- \`spec-*.md\` → spec
+- \`review-*.md\` → review
+- \`decision-*.md\` → decision
+- \`proposal-*.md\` → proposal
+- \`bugfix-*.md\` → bugfix
+- anything else → note
+
+**Resolving "the spec we just worked on":**
+- If a file was recently edited in this session matching the conventions
+  above, push that file.
+- If content was drafted inline in the conversation, write it to a file
+  first (e.g., \`/tmp/spec-xxx.md\`) then push.
+
+**Teammate names:** first name usually works (\`codiedev ping nic ...\`).
+If ambiguous, the CLI returns candidates — retry with the full email.
+
+**Errors:**
+- "not connected" → user needs to run \`npx codiedev connect\` with their
+  API token from https://codiedev.com/portal/integrations/claude-code
+- "ambiguous recipient" → surface candidates to the user
+`;
+/**
+ * Write the codiedev agent-facing docs block to the user-level Claude
+ * instructions file so Claude Code picks up the commands in every session
+ * (no per-repo CLAUDE.md needed). Idempotent — replaces the existing block
+ * between its begin/end markers on re-run.
+ */
+function writeInstructionsBlock(targetPath) {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const block = `${CODIEDEV_INSTRUCTIONS_BEGIN}\n` +
+        CODIEDEV_INSTRUCTIONS_BODY +
+        `\n${CODIEDEV_INSTRUCTIONS_END}\n`;
+    let existing = "";
+    if (fs.existsSync(targetPath)) {
+        existing = fs.readFileSync(targetPath, "utf8");
+    }
+    const beginIdx = existing.indexOf(CODIEDEV_INSTRUCTIONS_BEGIN);
+    const endIdx = existing.indexOf(CODIEDEV_INSTRUCTIONS_END);
+    let next;
+    if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+        // Replace the existing block in place.
+        next =
+            existing.slice(0, beginIdx) +
+                block +
+                existing.slice(endIdx + CODIEDEV_INSTRUCTIONS_END.length);
+    }
+    else if (existing.trim()) {
+        // Append with a blank-line separator.
+        next = existing.replace(/\n*$/, "\n\n") + block;
+    }
+    else {
+        next = block;
+    }
+    fs.writeFileSync(targetPath, next, "utf8");
+}
+function installClaudeCodeInstructions() {
+    writeInstructionsBlock(CLAUDE_USER_INSTRUCTIONS_PATH);
+}
+function installCodexInstructions() {
+    writeInstructionsBlock(CODEX_USER_INSTRUCTIONS_PATH);
+}
 /**
  * Install the CodieDev MCP server into Claude Code's user-scope config.
  * Safe to call multiple times — updates the existing entry if present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codiedev",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Connect Claude Code or Codex to CodieDev for org-wide session capture and artifact collaboration",
   "bin": {
     "codiedev": "./dist/cli.js",