@orderful/droid 0.48.0 → 0.51.0

package/src/tools/project/skills/project/references/pushing.md

@@ -0,0 +1,79 @@
+# Pushing to Codex
+
+**Trigger:** `/project push [codex:{name}]`
+
+Push team-relevant content from a local project back to the shared codex.
+
+## What Gets Shared
+
+Not everything in a project is codex-worthy. Extract only team-relevant content:
+
+| Share | Don't Share |
+|-------|-------------|
+| Architecture decisions with rationale | Personal work notes |
+| New patterns discovered during implementation | In-progress tasks |
+| Updated technical constraints | Session logs or worklogs |
+| Status changes (shipped, blocked, pivoted) | Brain docs or research drafts |
+| Key file paths or API changes | Local configuration |
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user which codex project to update, save to frontmatter
+   - Codex project must already exist. If it doesn't, suggest `/codex new project {name}` first.
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first
+
+3. **Read PROJECT.md** and companion docs (DECISIONS.md, WORKLOG.md if they exist)
+
+4. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Read existing codex project docs
+
+5. **Extract and categorise shareable content:**
+   - **Decisions:** New entries from DECISIONS.md or inline decisions in PROJECT.md
+   - **Architecture:** Changes to technical approach, new patterns, updated diagrams
+   - **Status:** Phase changes, milestones hit, scope changes
+   - **Constraints:** Newly discovered technical constraints or gotchas
+
+6. **Propose codex updates** (never auto-apply):
+   - For each item, show:
+     - What will be added/changed in codex
+     - Which codex file it targets (DECISIONS.md, TECH-DESIGN.md, PRD.md)
+     - A diff preview
+   - Let user accept, reject, or edit each item
+
+7. **After approval:**
+   - Use codex git scripts for the write operation:
+     ```bash
+     # Start write
+     droid config --get tools.codex | droid exec codex git-start-write --config - \
+       --branch codex/sync-{project-name}
+
+     # Make changes to codex files
+
+     # Normalize frontmatter
+     droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+     # Finish write (commit + PR)
+     droid config --get tools.codex | droid exec codex git-finish-write --config - \
+       --message "sync({project}): {summary}" \
+       --pr-title "sync({project}): Update from local project" \
+       --pr-body "{description of changes}"
+     ```
+   - Update local PROJECT.md sync marker:
+     ```
+     **Last pushed:** {date} to codex:{name}
+     ```
+
+## Key Principles
+
+- **Curated, not automated** — user explicitly reviews what gets shared
+- **PR-based** — codex changes go through PR review, not direct commits
+- **Additive** — adds to codex content, doesn't overwrite others' contributions
+- **Idempotent** — running `/project push` twice proposes only new/changed content

package/src/tools/release/TOOL.yaml

@@ -2,6 +2,8 @@ name: release
 description: "Release ceremony automation — create release PRs, check status, notify Slack."
 version: 0.2.2
 status: alpha
+audience:
+  - engineering
 
 includes:
   skills:

package/src/tools/share/TOOL.yaml

@@ -2,6 +2,8 @@ name: share
 description: "Share content to external platforms. Publish docs to Confluence or post summaries to Slack."
 version: 0.1.1
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/src/tools/status-update/TOOL.yaml

@@ -2,6 +2,10 @@ name: status-update
 description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
 version: 0.2.2
 status: beta
+audience:
+  - engineering
+  - product
+  - design
 
 includes:
   skills:

package/src/tools/tech-design/TOOL.yaml

@@ -2,6 +2,8 @@ name: tech-design
 description: "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review)."
 version: 0.3.1
 status: beta
+audience:
+  - engineering
 
 includes:
   skills:

package/src/tools/wrapup/TOOL.yaml

@@ -2,6 +2,8 @@ name: wrapup
 description: "Session wrap-up that captures decisions, learnings, and open items to persistent docs."
 version: 0.1.5
 status: alpha
+audience:
+  - all
 
 includes:
   skills:

package/dist/tools/codex/skills/codex/scripts/git-scripts.test.ts

@@ -1,364 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
-import { execSync, spawnSync } from 'child_process';
-import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-/**
- * Integration tests for codex git scripts.
- *
- * These tests create real git repos and run the actual scripts,
- * validating both the JSON output and the resulting git state.
- */
-
-const SCRIPTS_DIR = __dirname;
-
-interface ScriptResult {
-  success: boolean;
-  branch?: string;
-  stashed?: boolean;
-  from?: string;
-  pr_url?: string;
-  error?: string;
-}
-
-function runScript(
-  scriptName: string,
-  args: string[],
-  config: Record<string, unknown>
-): ScriptResult {
-  const scriptPath = join(SCRIPTS_DIR, `${scriptName}.ts`);
-  const configJson = JSON.stringify(config);
-
-  const result = spawnSync('bun', ['run', scriptPath, '--config', configJson, ...args], {
-    encoding: 'utf-8',
-    cwd: process.cwd(),
-  });
-
-  if (result.error) {
-    return { success: false, error: result.error.message };
-  }
-
-  try {
-    return JSON.parse(result.stdout.trim());
-  } catch {
-    return {
-      success: false,
-      error: `Failed to parse output: ${result.stdout}\nStderr: ${result.stderr}`,
-    };
-  }
-}
-
-function git(cwd: string, ...args: string[]): string {
-  // Quote arguments that contain spaces
-  const quotedArgs = args.map(arg => (arg.includes(' ') ? `"${arg}"` : arg));
-  return execSync(`git ${quotedArgs.join(' ')}`, { cwd, encoding: 'utf-8' }).trim();
-}
-
-function createTestRepo(): { repo: string; remote: string } {
-  // Create temp directories for repo and "remote"
-  const baseDir = mkdtempSync(join(tmpdir(), 'codex-test-'));
-  const remoteDir = join(baseDir, 'remote.git');
-  const repoDir = join(baseDir, 'repo');
-
-  // Create bare "remote" repo
-  mkdirSync(remoteDir);
-  git(remoteDir, 'init', '--bare');
-
-  // Create working repo
-  mkdirSync(repoDir);
-  git(repoDir, 'init');
-  git(repoDir, 'config', 'user.email', 'test@test.com');
-  git(repoDir, 'config', 'user.name', 'Test User');
-
-  // Create initial commit
-  writeFileSync(join(repoDir, 'README.md'), '# Test Repo\n');
-  git(repoDir, 'add', '.');
-  git(repoDir, 'commit', '-m', 'Initial commit');
-
-  // Rename to main if needed
-  try {
-    git(repoDir, 'branch', '-M', 'main');
-  } catch {
-    // Already on main
-  }
-
-  // Add remote and push
-  git(repoDir, 'remote', 'add', 'origin', remoteDir);
-  git(repoDir, 'push', '-u', 'origin', 'main');
-
-  return { repo: repoDir, remote: remoteDir };
-}
-
-function createTestRepoSimple(): string {
-  const { repo } = createTestRepo();
-  return repo;
-}
-
-function cleanupTestRepo(path: string): void {
-  try {
-    rmSync(path, { recursive: true, force: true });
-  } catch {
-    // Ignore cleanup errors
-  }
-}
-
-describe('git-preamble', () => {
-  let testRepo: string;
-  let baseDir: string;
-
-  beforeEach(() => {
-    const { repo } = createTestRepo();
-    testRepo = repo;
-    // baseDir is the parent of repo
-    baseDir = join(testRepo, '..');
-  });
-
-  afterEach(() => {
-    cleanupTestRepo(baseDir);
-  });
-
-  it('succeeds on clean main branch', () => {
-    const result = runScript('git-preamble', [], { codex_repo: testRepo });
-
-    expect(result.success).toBe(true);
-    expect(result.branch).toBe('main');
-    expect(result.stashed).toBe(false);
-  });
-
-  it('returns to main from feature branch', () => {
-    // Create and checkout a feature branch
-    git(testRepo, 'checkout', '-b', 'feature/test');
-
-    const result = runScript('git-preamble', [], { codex_repo: testRepo });
-
-    expect(result.success).toBe(true);
-    expect(result.branch).toBe('main');
-
-    // Verify we're actually on main
-    const currentBranch = git(testRepo, 'branch', '--show-current');
-    expect(currentBranch).toBe('main');
-  });
-
-  it('stashes uncommitted changes', () => {
-    // Create uncommitted changes
-    writeFileSync(join(testRepo, 'dirty.txt'), 'uncommitted');
-    git(testRepo, 'add', 'dirty.txt');
-
-    const result = runScript('git-preamble', [], { codex_repo: testRepo });
-
-    expect(result.success).toBe(true);
-    expect(result.stashed).toBe(true);
-
-    // Verify the file is no longer in working directory
-    const status = git(testRepo, 'status', '--porcelain');
-    expect(status).toBe('');
-  });
-
-  it('fails with missing repo', () => {
-    const result = runScript('git-preamble', [], { codex_repo: '/nonexistent/path' });
-
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('not found');
-  });
-
-  it('aborts stuck rebase', () => {
-    // Create a situation with a stuck rebase (simulate by creating the file)
-    mkdirSync(join(testRepo, '.git', 'rebase-merge'), { recursive: true });
-    writeFileSync(join(testRepo, '.git', 'rebase-merge', 'git-rebase-todo'), '');
-
-    const result = runScript('git-preamble', [], { codex_repo: testRepo });
-
-    // Should succeed after aborting the rebase
-    expect(result.success).toBe(true);
-  });
-});
-
-describe('git-start-write', () => {
-  let testRepo: string;
-  let baseDir: string;
-
-  beforeEach(() => {
-    const { repo } = createTestRepo();
-    testRepo = repo;
-    baseDir = join(testRepo, '..');
-  });
-
-  afterEach(() => {
-    cleanupTestRepo(baseDir);
-  });
-
-  it('creates a new branch from main', () => {
-    const result = runScript('git-start-write', ['--branch', 'codex/test-branch'], {
-      codex_repo: testRepo,
-    });
-
-    expect(result.success).toBe(true);
-    expect(result.branch).toBe('codex/test-branch');
-    expect(result.from).toBe('main');
-
-    // Verify we're on the new branch
-    const currentBranch = git(testRepo, 'branch', '--show-current');
-    expect(currentBranch).toBe('codex/test-branch');
-  });
-
-  it('resets existing branch to main', () => {
-    // Create branch with a commit
-    git(testRepo, 'checkout', '-b', 'codex/existing');
-    writeFileSync(join(testRepo, 'old-file.txt'), 'old content');
-    git(testRepo, 'add', '.');
-    git(testRepo, 'commit', '-m', 'Old commit');
-    git(testRepo, 'checkout', 'main');
-
-    // Start write should reset it
-    const result = runScript('git-start-write', ['--branch', 'codex/existing'], {
-      codex_repo: testRepo,
-    });
-
-    expect(result.success).toBe(true);
-
-    // The old file should not exist (branch was reset)
-    expect(existsSync(join(testRepo, 'old-file.txt'))).toBe(false);
-  });
-
-  it('fails without branch argument', () => {
-    const result = runScript('git-start-write', [], { codex_repo: testRepo });
-
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('--branch');
-  });
-
-  it('runs preamble first (returns from feature branch)', () => {
-    // Start on a different branch
-    git(testRepo, 'checkout', '-b', 'feature/other');
-
-    const result = runScript('git-start-write', ['--branch', 'codex/new'], {
-      codex_repo: testRepo,
-    });
-
-    expect(result.success).toBe(true);
-    expect(result.branch).toBe('codex/new');
-  });
-});
-
-describe('git-finish-write', () => {
-  let testRepo: string;
-  let baseDir: string;
-
-  beforeEach(() => {
-    const { repo } = createTestRepo();
-    testRepo = repo;
-    baseDir = join(testRepo, '..');
-    // Start on a feature branch (simulating after git-start-write)
-    git(testRepo, 'checkout', '-b', 'codex/test-feature');
-  });
-
-  afterEach(() => {
-    cleanupTestRepo(baseDir);
-  });
-
-  it('commits changes and returns to main', () => {
-    // Create a change
-    writeFileSync(join(testRepo, 'new-file.md'), '# New Content\n');
-
-    const result = runScript(
-      'git-finish-write',
-      ['--message', 'test: add new file', '--pr-title', 'Test PR', '--pr-body', 'Test body'],
-      { codex_repo: testRepo }
-    );
-
-    // Note: PR creation will fail (no remote), but commit should succeed
-    // and we should return to main
-    const currentBranch = git(testRepo, 'branch', '--show-current');
-    expect(currentBranch).toBe('main');
-
-    // Verify the commit exists on the feature branch
-    const log = git(testRepo, 'log', 'codex/test-feature', '--oneline', '-1');
-    expect(log).toContain('test: add new file');
-  });
-
-  it('fails when on main branch', () => {
-    git(testRepo, 'checkout', 'main');
-
-    const result = runScript(
-      'git-finish-write',
-      ['--message', 'bad commit', '--pr-title', 'Bad PR'],
-      { codex_repo: testRepo }
-    );
-
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('Cannot commit directly to main');
-  });
-
-  it('fails with no changes to commit', () => {
-    const result = runScript(
-      'git-finish-write',
-      ['--message', 'empty commit', '--pr-title', 'Empty PR'],
-      { codex_repo: testRepo }
-    );
-
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('No changes to commit');
-  });
-
-  it('fails without required arguments', () => {
-    const noMessage = runScript('git-finish-write', ['--pr-title', 'Test'], {
-      codex_repo: testRepo,
-    });
-    expect(noMessage.success).toBe(false);
-    expect(noMessage.error).toContain('--message');
-
-    const noTitle = runScript('git-finish-write', ['--message', 'Test'], {
-      codex_repo: testRepo,
-    });
-    expect(noTitle.success).toBe(false);
-    expect(noTitle.error).toContain('--pr-title');
-  });
-});
-
-describe('full workflow', () => {
-  let testRepo: string;
-  let baseDir: string;
-
-  beforeEach(() => {
-    const { repo } = createTestRepo();
-    testRepo = repo;
-    baseDir = join(testRepo, '..');
-  });
-
-  afterEach(() => {
-    cleanupTestRepo(baseDir);
-  });
-
-  it('preamble -> start-write -> make changes -> finish-write', () => {
-    // 1. Preamble
-    const preamble = runScript('git-preamble', [], { codex_repo: testRepo });
-    expect(preamble.success).toBe(true);
-
-    // 2. Start write
-    const start = runScript('git-start-write', ['--branch', 'codex/full-test'], {
-      codex_repo: testRepo,
-    });
-    expect(start.success).toBe(true);
-    expect(start.branch).toBe('codex/full-test');
-
-    // 3. Make changes (create directory first)
-    mkdirSync(join(testRepo, 'topics'), { recursive: true });
-    writeFileSync(join(testRepo, 'topics', 'test-topic.md'), '# Test Topic\n');
-
-    // 4. Finish write (PR will fail but commit should work)
-    const finish = runScript(
-      'git-finish-write',
-      ['--message', 'topic: add test-topic', '--pr-title', 'Topic: test-topic'],
-      { codex_repo: testRepo }
-    );
-
-    // Should return to main regardless of PR status
-    const currentBranch = git(testRepo, 'branch', '--show-current');
-    expect(currentBranch).toBe('main');
-
-    // Verify commit exists on feature branch
-    const commits = git(testRepo, 'log', 'codex/full-test', '--oneline');
-    expect(commits).toContain('topic: add test-topic');
-  });
-});