From 7c224e5dca00f1598abb8c2055d08ff3dc4bb6a2 Mon Sep 17 00:00:00 2001 From: Leandro Stasi Date: Fri, 5 Jun 2026 11:53:08 +0200 Subject: [PATCH 1/2] Proposal: Multi-Tool Configuration for Claude Code & OpenAI Codex Fixes #3 --- AGENTS.md | 25 + CLAUDE.md | 88 +-- CORE.md | 88 +++ README.md | 570 ++++++------------ agents/planner.md | 8 +- .../keybindings.json | 0 settings.json => claude-code/settings.json | 0 codex/AGENTS.md | 32 + codex/README.md | 10 + codex/config.toml | 14 + .../prompts/architecture-decision-records.md | 10 + codex/prompts/create-plan.md | 10 + codex/prompts/deep-spec-review.md | 10 + codex/prompts/execute-plan.md | 10 + codex/prompts/sdd-delivery-artifacts.md | 10 + codex/prompts/sdd-facts.md | 10 + codex/prompts/sdd-refine.md | 10 + codex/prompts/sdd-research.md | 10 + codex/prompts/sdd-start.md | 10 + codex/prompts/spec-review.md | 10 + scripts/generate-codex-agents.sh | 102 ++++ scripts/install-claude-code.sh | 80 +++ scripts/install-codex.sh | 95 +++ skills/spec-review/SKILL.md | 6 + 24 files changed, 754 insertions(+), 464 deletions(-) create mode 100644 AGENTS.md create mode 100644 CORE.md rename keybindings.json => claude-code/keybindings.json (100%) rename settings.json => claude-code/settings.json (100%) create mode 100644 codex/AGENTS.md create mode 100644 codex/README.md create mode 100644 codex/config.toml create mode 100644 codex/prompts/architecture-decision-records.md create mode 100644 codex/prompts/create-plan.md create mode 100644 codex/prompts/deep-spec-review.md create mode 100644 codex/prompts/execute-plan.md create mode 100644 codex/prompts/sdd-delivery-artifacts.md create mode 100644 codex/prompts/sdd-facts.md create mode 100644 codex/prompts/sdd-refine.md create mode 100644 codex/prompts/sdd-research.md create mode 100644 codex/prompts/sdd-start.md create mode 100644 codex/prompts/spec-review.md create mode 100755 scripts/generate-codex-agents.sh create mode 100755 scripts/install-claude-code.sh create mode 100755 scripts/install-codex.sh diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..42f4af2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# AGENTS.md + +OpenAI Codex wrapper for this configuration repository. + +## Shared Core + +Read and apply `CORE.md` before doing work. It is the source of truth for tool-agnostic behavior: + +- Think before coding. +- Prefer the simplest implementation that solves the request. +- Make surgical changes only. +- Define success criteria and verify results. + +## Repository Assets + +This repository provides reusable assets for Claude Code and OpenAI Codex: + +- `agents/` contains the canonical agent definitions. +- `skills/` contains reusable workflow skills. +- `commands/` contains command-style prompts. +- `rules/` contains standards and workflow rules loaded on demand. +- `claude-code/` contains Claude Code-specific configuration files. +- `codex/` contains OpenAI Codex-specific adapter files. + +When a skill or agent references `rules/...`, resolve that path from this repository unless the active project has its own closer `rules/...`. diff --git a/CLAUDE.md b/CLAUDE.md index 6e4c6f5..3c4ffc5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,83 +1,23 @@ # CLAUDE.md -Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. +Claude Code wrapper for the shared AI coding instructions in this repository. -**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. +## Shared Core -## Response Brevity +Read and apply `CORE.md` before doing work. It is the source of truth for tool-agnostic behavior: -- Default to concise responses: max 900 output tokens unless explicitly asked for more -- Use bullet points and section-by-section breakdowns for long topics -- When asking clarifying questions, ask ONE at a time and wait for the answer -- If a topic requires more than ~900 tokens, propose a section-by-section approach first +- Think before coding. +- Prefer the simplest implementation that solves the request. +- Make surgical changes only. +- Define success criteria and verify results. -## Scope Discipline +## Claude Code Assets -- For spec/documentation tasks, ONLY edit documentation files - never modify application code unless explicitly asked -- Before making changes outside the originally named files, ask first -- Distinguish between 'document where X should happen' (spec edit only) vs 'implement X' (code change) +This repository also provides Claude Code agents, skills, commands, and rule documents: -## Spec Workflow +- `agents/` contains Claude Code subagent definitions. +- `skills/` contains reusable workflow skills. +- `commands/` contains slash command prompts. +- `rules/` contains standards and workflow rules loaded on demand. -- When reviewing specs, follow this pattern: (1) read all relevant docs, (2) identify ambiguities, (3) ask clarifying questions one at a time, (4) apply edits after all decisions are confirmed -- Do not start writing plan.md or implementation files until spec questions are resolved - -## Think Before Coding - -**Don't assume. Don't hide confusion. Surface tradeoffs.** - -Before implementing: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them - don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -## Simplicity First - -**Minimum code that solves the problem. Nothing speculative.** - -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. - -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. - -## Surgical Changes - -**Touch only what you must. Clean up only your own mess.** - -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, mention it - don't delete it. - -When your changes create orphans: -- Remove imports/variables/functions that YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. - -The test: Every changed line should trace directly to the user's request. - -## Goal-Driven Execution - -**Define success criteria. Loop until verified.** - -Transform tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - -For multi-step tasks, state a brief plan: -``` -1. [Step] → verify: [check] -2. [Step] → verify: [check] -3. [Step] → verify: [check] -``` - -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. - ---- - -**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. +When installed globally, these files normally live under `~/.claude/`. diff --git a/CORE.md b/CORE.md new file mode 100644 index 0000000..67ade0f --- /dev/null +++ b/CORE.md @@ -0,0 +1,88 @@ +# Core AI Coding Instructions + +Tool-agnostic behavioral guidelines to reduce common LLM coding mistakes. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## Response Brevity + +- Default to concise responses: max 900 output tokens unless explicitly asked for more. +- Use bullet points and section-by-section breakdowns for long topics. +- When asking clarifying questions, ask one at a time and wait for the answer. +- If a topic requires more than about 900 tokens, propose a section-by-section approach first. + +## Scope Discipline + +- For spec/documentation tasks, edit only documentation files; never modify application code unless explicitly asked. +- Before making changes outside the originally named files, ask first. +- Distinguish between "document where X should happen" (spec edit only) and "implement X" (code change). + +## Spec Workflow + +- When reviewing specs, follow this pattern: read all relevant docs, identify ambiguities, ask clarifying questions one at a time, then apply edits after all decisions are confirmed. +- Do not start writing `plan.md` or implementation files until spec questions are resolved. + +## Think Before Coding + +**Do not assume. Do not hide confusion. Surface tradeoffs.** + +Before implementing: + +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them; do not pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop, name what is confusing, and ask. + +## Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that was not requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: + +- Do not "improve" adjacent code, comments, or formatting. +- Do not refactor things that are not broken. +- Match existing style, even if you would do it differently. +- If you notice unrelated dead code, mention it; do not delete it. + +When your changes create orphans: + +- Remove imports, variables, and functions that your changes made unused. +- Do not remove pre-existing dead code unless asked. + +The test: every changed line should trace directly to the user's request. + +## Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: + +- "Add validation" -> "Write tests for invalid inputs, then make them pass." +- "Fix the bug" -> "Write a test that reproduces it, then make it pass." +- "Refactor X" -> "Ensure tests pass before and after." + +For multi-step tasks, state a brief plan: + +```text +1. [Step] -> verify: [check] +2. [Step] -> verify: [check] +3. [Step] -> verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria, such as "make it work", require constant clarification. + +--- + +These guidelines are working if there are fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. diff --git a/README.md b/README.md index 19dcbb6..1fbce62 100644 --- a/README.md +++ b/README.md @@ -1,440 +1,251 @@ -# Claude Code Configuration +# AI Coding Assistant Configuration -A set of agents, skills, and rules for disciplined AI-assisted development with [Claude Code](https://claude.ai/code). +Shared agents, skills, rules, and behavioral constraints for disciplined AI-assisted development with Claude Code and OpenAI Codex. -## What's in here +The repository keeps tool-agnostic behavior in `CORE.md`, then adapts it to each assistant through lightweight tool-specific files. -### `CLAUDE.md` +## What Is Included -The main instruction file loaded by Claude Code in every session. +### Shared Core -It should stay small and define only the core behavioural constraints: +- `CORE.md` — tool-agnostic behavioral constraints: + - Think before coding. + - Simplicity first. + - Surgical changes. + - Goal-driven execution. +- `agents/` — source agent definitions. +- `skills/` — reusable workflow skills. +- `rules/` — standards and workflow rules loaded on demand. +- `commands/` — command-style prompts. -- Think before coding — state assumptions explicitly and surface ambiguities. -- Simplicity first — write the minimum code that solves the problem. -- Surgical changes — touch only what the task requires. -- Goal-driven execution — define success criteria and verify results. +### Claude Code Files -Workflow-specific guidance should live in `rules/` and `skills/`, not directly in `CLAUDE.md`. +- `CLAUDE.md` — Claude Code wrapper that points to `CORE.md`. +- `claude-code/settings.json` — Claude Code permissions, model, token, and status-line settings. +- `claude-code/keybindings.json` — Claude Code chat keybindings. -### `agents/` +### OpenAI Codex Files -Custom subagent definitions. Each agent has a narrow, well-defined role: +- `AGENTS.md` — repository-level Codex wrapper that points to `CORE.md`. +- `codex/AGENTS.md` — Codex wrapper that points to `CORE.md`. +- `codex/config.toml` — minimal Codex config fragment. +- `scripts/generate-codex-agents.sh` — generates Codex custom-agent TOML from `agents/*.md` during install. +- `codex/prompts/*.md` — legacy custom prompt wrappers for command-like entrypoints. -| Agent | Role | -|-------|------| -| `planner` | Converts an approved task/spec into a deterministic `plan.md` | -| `implementer` | Executes an approved `plan.md` with minimal changes | -| `reviewer` | Reviews code changes against the plan, spec, and delivery artifacts | -| `antagonist` | Adversarial pre-PR reviewer: looks for blockers, hidden risks, weak validation, unsafe rollout, and scope creep | -| `tdd-guide` | Enforces test-first workflow: red → green → refactor | -| `tech-lead` | Research and planning only — never modifies code | +## Install For Claude Code -### `skills/` +Run one command from the repository root: -Slash commands that orchestrate multi-step workflows: - -| Skill | Command | What it does | -|-------|---------|--------------| -| `sdd-start` | `/sdd-start` | Creates an intent-level `spec.md` v0 from a rough requirement, using `AskUserQuestionTool` to resolve blocking ambiguities | -| `sdd-research` | `/sdd-research` | Inspects the repository against `spec.md` and writes `research.md` with concrete code evidence | -| `sdd-refine` | `/sdd-refine` | Refines `spec.md` using `research.md`, producing the planning-ready version | -| `sdd-delivery-artifacts` | `/sdd-delivery-artifacts` | Creates `delivery_artifacts/*.md`, a feature-specific map of what must be produced or modified | -| `sdd-facts` | `/sdd-facts` | Creates `facts/*.md`, executable or verifiable assertions that prove important requirements | -| `execute-plan` | `/execute-plan` | Reads `plan.md` and drives every task to completion using a TDD loop, parallelizing disjoint tasks when safe | -| `deep-spec-review` | `/deep-spec-review` | Runs specialist reviewers in parallel — security, cost, compliance, ops, architecture — and conducts structured Q&A before edits | -| `architecture-decision-records` | `/architecture-decision-records` | Captures architectural decisions as structured ADR documents in `docs/adr/` | -| `spec-review` | `/spec-review` | Lightweight spec review | - -### `rules/` +```bash +./scripts/install-claude-code.sh +``` -Domain-specific standards and workflow rules loaded on demand: +The installer copies files into `~/.claude` by default: ```text -rules/ -├── common/ # Coding style, testing, security, patterns, hooks, devkit, jt-linter -├── rails/ # Rails-specific style, testing, security, patterns, hooks -├── terraform/ # Terraform, DynamoDB, IAM and infrastructure rules -└── sdd/ # Spec-Driven Development workflow and artifact rules +~/.claude/ +├── CLAUDE.md +├── CORE.md +├── agents/ +├── skills/ +├── rules/ +├── commands/ +├── settings.json +└── keybindings.json ``` -### `settings.json` and `keybindings.json` - -Claude Code configuration files for project-specific settings: -- `settings.json` — Permissions allowlist, model selection, token limits, and status line customization -- `keybindings.json` — Custom keyboard shortcuts for Claude Code chat - -## Installation & Setup - -This repository contains Claude Code configuration files (agents, skills, rules, and behavioral constraints) that you install once to use across all your projects. - -### Installation - -1. Clone this repository: - ```bash - git clone https://github.com/Legrandk/claude.git - cd claude - ``` - -2. Copy the configuration files to your home directory where Claude Code looks for them: - ```bash - # macOS/Linux - mkdir -p ~/.claude - cp -r agents/ ~/.claude/ - cp -r skills/ ~/.claude/ - cp -r rules/ ~/.claude/ - cp CLAUDE.md ~/.claude/ - - # Windows - mkdir %USERPROFILE%\.claude - xcopy agents\ %USERPROFILE%\.claude\agents\ /E /I - xcopy skills\ %USERPROFILE%\.claude\skills\ /E /I - xcopy rules\ %USERPROFILE%\.claude\rules\ /E /I - copy CLAUDE.md %USERPROFILE%\.claude\ - ``` - -3. Restart Claude Code (web interface or VS Code extension) if it's already running. - -### Verification - -After installation, open Claude Code in ANY project and test: - -1. **Check agents** — Type `@` in chat and you should see: - - `@planner` - - `@implementer` - - `@reviewer` - - `@antagonist` - - `@tech-lead` - - `@tdd-guide` - -2. **Check slash commands** — Type `/` in chat and you should see: - - `/sdd-start` - - `/sdd-research` - - `/sdd-refine` - - `/execute-plan` - - `/deep-spec-review` - - And more... - -3. **Check CLAUDE.md** — The core behavioral constraints should be active: - - Think before coding - - Simplicity first - - Surgical changes - - Goal-driven execution - -### Usage - -Once installed, these tools are available in every Claude Code session: +Set `CLAUDE_HOME` to install somewhere else: ```bash -# Start a new feature with spec-driven development -/sdd-start doc/playbook/20260603_my_feature +CLAUDE_HOME=/path/to/.claude ./scripts/install-claude-code.sh +``` -# Ask the planner to create a plan -@planner Review this spec and create a plan.md +### Verify Claude Code -# Execute the plan -/execute-plan +After installation, restart Claude Code and check: -# Review the changes -@reviewer Check if implementation matches the plan -``` +- Type `@` and confirm agents such as `@planner`, `@implementer`, `@reviewer`, `@antagonist`, `@tech-lead`, and `@tdd-guide` are available. +- Type `/` and confirm workflow commands such as `/sdd-start`, `/sdd-research`, `/sdd-refine`, and `/execute-plan` are available. +- Confirm the shared constraints from `CORE.md` are active. -### Updating +## Install For OpenAI Codex -To update to the latest version: +Run one command from the repository root: ```bash -cd claude -git pull -cp -r agents/ skills/ rules/ CLAUDE.md ~/.claude/ +./scripts/install-codex.sh ``` -### Optional: Claude Code Settings - -The repository also includes optional Claude Code configuration files: - -- **settings.json** — Claude Code permissions, model selection, status line customization -- **keybindings.json** — Custom keyboard shortcuts for Claude Code - -These are project-specific and typically stay in the repository rather than being installed globally. They configure Claude Code behavior when working on projects (e.g., allowed bash commands, output token limits). +The installer copies Codex files into `~/.codex` and shared skills/rules into `~/.agents`: -If you want to use these settings as defaults for all projects, you can copy them to your Claude Code configuration directory (location varies by Claude Code version and platform - check Claude Code documentation). - -## Using with Claude Code - -### Invoking Agents - -To use a specific agent, type `@agent-name` in Claude Code chat: +```text +~/.codex/ +├── AGENTS.md +├── CORE.md +├── agents/ +│ ├── planner.toml +│ ├── implementer.toml +│ └── ... +├── prompts/ +└── config.toml +~/.agents/ +├── agents/ +├── skills/ +├── rules/ +└── commands/ ``` -@planner Convert this requirement into a plan.md -``` - -Available agents: -- `@planner` — Creates a deterministic plan from a task/spec -- `@implementer` — Executes the plan with minimal changes -- `@reviewer` — Reviews code against plan, spec, and artifacts -- `@antagonist` — Adversarial pre-PR review for risks and blockers -- `@tech-lead` — Research and planning (read-only, no code changes) -- `@tdd-guide` — Enforces test-first workflow -### Using Slash Commands +If `~/.codex/config.toml` already exists, the installer leaves it unchanged and writes `~/.codex/config.claude-shared.example.toml` for review. All other Codex assets are still installed. -Slash commands orchestrate multi-step workflows. Type `/` in Claude Code to see available commands: +Set `CODEX_HOME` or `AGENTS_HOME` to install somewhere else: +```bash +CODEX_HOME=/path/to/.codex AGENTS_HOME=/path/to/.agents ./scripts/install-codex.sh ``` -/sdd-start # Start a new feature with intent-level spec -/sdd-research # Research the repository -/sdd-refine # Refine spec with research findings -/sdd-delivery-artifacts # Map feature requirements -/sdd-facts # Create verifiable assertions -/execute-plan # Drive tasks to completion -/deep-spec-review # Parallel specialist reviewers -/architecture-decision-records # Capture ADRs -/spec-review # Lightweight spec review -``` - -### Core Behavioral Constraints - -When you use Claude Code in this workspace, `CLAUDE.md` automatically loads four core principles: - -1. **Think before coding** — state assumptions, surface ambiguities -2. **Simplicity first** — minimum code that solves the problem -3. **Surgical changes** — touch only what's necessary -4. **Goal-driven execution** — define success criteria and verify - -Domain-specific rules from `rules/` (Rails, Terraform, testing, security, etc.) are loaded on demand based on your project context. - -## How it works - -There are two main operating modes. - -### Lightweight mode - -Use this for trivial or mechanical work: - -1. **Plan** — invoke the `planner` agent with a task description. -2. **Execute** — run `/execute-plan`. -3. **Review** — invoke the `reviewer` agent. - -This mode is appropriate for: - -- typo fixes -- small copy changes -- obvious one-line configuration changes -- mechanical renames with no behavioural impact - -### Spec-Driven Development mode -Use SDD for non-trivial feature work, ambiguous requirements, behaviour changes, API changes, background jobs, observability changes, infrastructure changes, or anything where implementation should not start from a vague prompt. +### Verify Codex -The SDD workflow is: +After installation, restart Codex and check: -```text -/sdd-start - → spec.md v0 - -/sdd-research - → research.md - -/sdd-refine - → spec.md v1 - -/sdd-delivery-artifacts - → delivery_artifacts/*.md - -/sdd-facts - → facts/*.md - -planner - → plan.md + plan/tN.md - -/execute-plan - → code changes + validation + tracking updates - -reviewer - → final review against spec, research, delivery artifacts, facts, and plan - -antagonist - → adversarial pre-PR review for blockers, hidden risk, weak validation, unsafe rollout, and scope creep -``` +- Run `/skills` or type `$` and confirm skills such as `$sdd-start`, `$sdd-research`, `$sdd-refine`, and `$execute-plan` are available. +- Ask Codex to spawn a custom agent, for example: `Spawn the planner agent to review this spec`. +- Type `/` and look for prompt wrappers such as `/prompts:sdd-start` where custom prompts are enabled. +- Confirm `~/.codex/AGENTS.md`, `~/.codex/agents/planner.toml`, and `$HOME/.agents/skills/execute-plan/SKILL.md` exist. -The goal is to avoid jumping from a rough requirement directly into implementation. +## Install Both Tools -## How to use SDD - -Create a playbook directory for the feature: +Run both installers: -```text -doc/playbook/_/ +```bash +./scripts/install-claude-code.sh +./scripts/install-codex.sh ``` -Example: +Both tools use the same `CORE.md`, `agents/`, `skills/`, `rules/`, and `commands/` source files. -```text -doc/playbook/20260519_provider_output_observability/ -``` +## Feature Differences -### 1. Start from intent +| Capability | Claude Code | OpenAI Codex | +|------------|-------------|--------------| +| Core instructions | `CLAUDE.md` references `CORE.md` | `AGENTS.md` references `CORE.md` | +| Settings | JSON files under `~/.claude` | TOML config under `~/.codex/config.toml` | +| Agents | Invoked with `@agent-name` | Custom subagents in `~/.codex/agents/*.toml`; ask Codex to spawn them explicitly | +| Skills | Installed under `~/.claude/skills` | Installed under `$HOME/.agents/skills` | +| Commands | Claude slash commands | Codex skills via `/skills` or `$skill`; prompt wrappers under `~/.codex/prompts` where supported | +| Rules in this repo | Markdown workflow rules | Markdown workflow rules installed under `$HOME/.agents/rules`; Codex `.rules` command policies are separate | -Run: +Codex custom prompts are a compatibility bridge. Prefer Codex skills for reusable workflows when possible. -```text -/sdd-start doc/playbook/ -``` +## Updating -This creates: +Pull the latest repository changes and rerun the installer for the tool you use: -```text -spec.md +```bash +git pull +./scripts/install-claude-code.sh +# or +./scripts/install-codex.sh ``` -At this stage, `spec.md` is an intent-level spec. It should describe: - -- problem -- goal -- non-goals -- users or consumers -- desired behaviour -- EARS requirements -- acceptance scenarios -- observability expectations -- compatibility concerns -- research questions +Single-file configs are backed up before replacement when the target file already exists and differs. -`sdd-start` must not claim facts about the current codebase unless the user explicitly provided them. +## Usage -If current behaviour depends on repository inspection, the spec should say: +### Claude Code ```text -Unknown. Must be discovered during /sdd-research. -``` - -### 2. Research the repository - -Run: - -```text -/sdd-research doc/playbook/ +/sdd-start doc/playbook/20260603_my_feature +@planner Review this spec and create a plan.md +/execute-plan +@reviewer Check if implementation matches the plan ``` -This creates: +### OpenAI Codex ```text -research.md +$sdd-start doc/playbook/20260603_my_feature +Spawn the planner agent to review this spec and create a plan.md. +$execute-plan doc/playbook/20260603_my_feature +Spawn the reviewer agent to check if implementation matches the plan. ``` -`research.md` is the source of truth for repository evidence. It should record: +If custom prompts are enabled in your Codex surface, the prompt wrappers are also available as `/prompts:`. -- relevant files -- current flows -- existing tests -- contracts and external interfaces -- operational surfaces -- risks -- unknowns -- planning inputs +## Spec-Driven Development Workflow -It must not create a plan or modify code. +Use SDD for non-trivial feature work, ambiguous requirements, behavior changes, API changes, background jobs, observability changes, infrastructure changes, or anything where implementation should not start from a vague prompt. -### 3. Refine the spec - -Run: +The workflow is: ```text -/sdd-refine doc/playbook/ -``` +sdd-start + -> spec.md v0 -This updates `spec.md` using the evidence from `research.md`. +sdd-research + -> research.md -After this step, `spec.md` becomes the planning-ready version. +sdd-refine + -> spec.md v1 -The refined spec should reconcile: +sdd-delivery-artifacts + -> delivery_artifacts/*.md -```text -user intent + repository evidence -``` - -If research conflicts with the original intent, the conflict must be surfaced explicitly. The spec must not silently change product intent just because the current code makes something easier. - -### 4. Generate delivery artifacts +sdd-facts + -> facts/*.md -Run: +planner + -> plan.md + plan/tN.md -```text -/sdd-delivery-artifacts doc/playbook/ -``` +execute-plan + -> code changes + validation + tracking updates -This creates: +reviewer + -> final review against spec, research, delivery artifacts, facts, and plan -```text -delivery_artifacts/*.md +antagonist + -> adversarial pre-PR review for blockers, hidden risk, weak validation, unsafe rollout, and scope creep ``` -`delivery_artifacts/` is a variable, feature-specific map of what must be produced or modified. - -It is not a fixed category list. +### 1. Start From Intent -Examples of valid delivery artifact files: +Create a playbook directory for the feature: ```text -delivery_artifacts/ -├── 01-api-contracts.md -├── 02-domain-model.md -├── 03-jobs-consumers.md -└── 04-observability.md +doc/playbook/_/ ``` -or: - -```text -delivery_artifacts/ -├── 01-grafana-dashboard.md -├── 02-terraform-alerts.md -└── 03-runbook.md -``` +Run `sdd-start` with the playbook path. This creates `spec.md`, an intent-level spec describing the problem, goal, non-goals, desired behavior, requirements, acceptance scenarios, observability expectations, compatibility concerns, and research questions. -The actual files must be inferred from the feature. +At this stage, the spec must not claim facts about the current codebase unless the user explicitly provided them. Unknown current behavior should be marked for discovery during `sdd-research`. -Tests are not delivery artifacts. Tests belong in the plan and task validation sections. +### 2. Research The Repository -### 5. Generate facts +Run `sdd-research` with the playbook path. This creates `research.md`, the source of truth for repository evidence: relevant files, current flows, existing tests, contracts, operational surfaces, risks, unknowns, and planning inputs. -Run: +Research must not create a plan or modify code. -```text -/sdd-facts doc/playbook/ -``` +### 3. Refine The Spec -This creates: +Run `sdd-refine` with the playbook path. This updates `spec.md` using evidence from `research.md`. -```text -facts/*.md -``` +The refined spec reconciles user intent with repository evidence. If research conflicts with the original intent, the conflict must be surfaced explicitly. -Facts are executable or verifiable assertions. +### 4. Generate Delivery Artifacts -They exist because specs explain intent, but facts prove behaviour. +Run `sdd-delivery-artifacts` with the playbook path. This creates `delivery_artifacts/*.md`, a feature-specific map of what must be produced or modified. -A fact should link back to one or more `REQ-*` requirements and eventually be proven by a deterministic check, such as: +Tests are not delivery artifacts. Tests belong in the plan and task validation sections. -- test -- contract check -- schema validation -- smoke test -- static analysis -- infrastructure validation -- CI job +### 5. Generate Facts -Facts help reviewers answer: +Run `sdd-facts` with the playbook path. This creates `facts/*.md`, executable or verifiable assertions that prove the feature exists. -```text -Does this implementation actually prove the important behaviour, or does it merely look complete? -``` +Facts should link back to requirements and eventually be proven by deterministic checks such as tests, contract checks, schema validation, smoke tests, static analysis, infrastructure validation, or CI jobs. -### 6. Plan from the refined inputs +### 6. Plan From Refined Inputs -Invoke the `planner` agent only after these exist: +Invoke the planner only after these exist: ```text spec.md @@ -461,10 +272,7 @@ plan/t2.md ... ``` -The plan must cover: - -- every concrete artifact listed under `delivery_artifacts/*.md` -- every `@spec` fact listed under `facts/*.md` +The plan must cover every concrete artifact and every `@spec` fact. Each task should include: @@ -475,39 +283,24 @@ Each task should include: - validation/tests - done criteria -### 7. Execute the approved plan - -Run: - -```text -/execute-plan doc/playbook/ -``` +### 7. Execute The Approved Plan -Execution must follow the approved plan and modify only files allowed by the relevant task. +Run `execute-plan` with the playbook path. Execution must follow the approved plan and modify only files allowed by the relevant task. Validation must use the applicable project, stack, and common rules. -A task is not complete when code changes are implemented. A task is complete only when implementation, validation, and SDD tracking updates are all done. +A task is complete only when implementation, validation, and SDD tracking updates are all done. -After each verified task, `/execute-plan` must update the relevant tracking files when applicable: +After each verified task, `execute-plan` must update the relevant tracking files when applicable: - `plan.md` - `plan/tN.md` - `delivery_artifacts/*.md` - `facts/*.md` -### 8. Review the result - -Invoke the `reviewer` agent. +### 8. Review The Result -The review should check the diff against: - -- refined `spec.md` -- `research.md` -- `delivery_artifacts/*.md` -- `facts/*.md` -- `plan.md` -- completed `plan/tN.md` tasks +Invoke the reviewer agent. The review should check the diff against the refined spec, research, delivery artifacts, facts, plan, and completed task files. The reviewer should verify that: @@ -515,9 +308,9 @@ The reviewer should verify that: - facts marked `@implemented` have executable checks that exist and passed - completed tasks match the actual diff -### 9. Run the antagonist before PR +### 9. Run The Antagonist Before PR -Invoke the `antagonist` agent when the work is ready to become a PR. +Invoke the antagonist agent when the work is ready to become a PR. It looks for blockers, hidden risks, weak validation, unsafe rollout, and scope creep. The antagonist is not a normal reviewer. @@ -567,9 +360,9 @@ BLOCK | CAUTION | PASS The goal is to raise red flags before GitHub review, especially when AI-assisted implementation reduced the human owner's cognitive load. -## EARS requirements in specs +## EARS Requirements In Specs -Specs should use EARS for behavioural requirements. +Specs should use EARS for behavioral requirements. Each important requirement should: @@ -599,7 +392,7 @@ REQ-002: When recording provider output metrics, the system shall not include user-level identifiers as metric labels. REQ-003: -If the provider output attempt fails, then the system shall preserve the existing retry behaviour. +If the provider output attempt fails, then the system shall preserve the existing retry behavior. ``` Acceptance scenarios may use Given/When/Then, but they do not replace EARS requirements. @@ -612,7 +405,7 @@ The short version: ```text Specs explain intent. -Facts prove behaviour. +Facts prove behavior. ``` A fact should usually reference one or more `REQ-*` requirements. @@ -632,11 +425,11 @@ Executable check: Facts should not be marked `@implemented` unless the executable check exists and passed. -## SDD artifact responsibilities +## SDD Artifact Responsibilities | Artifact | Responsibility | |----------|----------------| -| `spec.md` | Behavioural source of truth | +| `spec.md` | Behavioral source of truth | | `research.md` | Repository-evidence source of truth | | `delivery_artifacts/*.md` | Production-scope source of truth | | `facts/*.md` | Executable-verification source of truth | @@ -644,46 +437,46 @@ Facts should not be marked `@implemented` unless the executable check exists and | `plan/tN.md` | Atomic task instructions | | tests/contracts/schemas/ADRs/dashboards/alerts/code | Permanent artifacts | -## Example: using the full flow +## Example: Using The Full Flow Imagine we want to add a small feature: ```text -When a user receives a very boring notification, the system should add a tiny fun fact to make it less depressing. +When a user receives a low-priority notification, the system should add a tiny fun fact to make it less depressing. ``` Start with a rough prompt: ```text -Help me write the specification for adding a tiny fun fact to boring notifications. +Help me write the specification for adding a tiny fun fact to low-priority notifications. The goal is to make low-priority notifications feel a bit more human without changing critical or legal messages. ``` Then run the flow: ```text -/sdd-start doc/playbook/20260601_fun_fact_notifications +sdd-start doc/playbook/20260601_fun_fact_notifications ``` -Claude should ask questions if the requirement is unclear, then create `spec.md`. +The assistant should ask questions if the requirement is unclear, then create `spec.md`. Next: ```text -/sdd-research doc/playbook/20260601_fun_fact_notifications +sdd-research doc/playbook/20260601_fun_fact_notifications ``` This checks the repo and answers questions like: - where notifications are built - whether notification priority already exists -- whether legal/critical messages can be detected +- whether legal or critical messages can be detected - where tests already live Then: ```text -/sdd-refine doc/playbook/20260601_fun_fact_notifications +sdd-refine doc/playbook/20260601_fun_fact_notifications ``` This turns the original intent into a repo-aware spec. @@ -691,7 +484,7 @@ This turns the original intent into a repo-aware spec. Then: ```text -/sdd-delivery-artifacts doc/playbook/20260601_fun_fact_notifications +sdd-delivery-artifacts doc/playbook/20260601_fun_fact_notifications ``` This lists what must be produced, for example: @@ -705,13 +498,13 @@ delivery_artifacts/ Then: ```text -/sdd-facts doc/playbook/20260601_fun_fact_notifications +sdd-facts doc/playbook/20260601_fun_fact_notifications ``` This defines what must be proven, for example: ```text -FACT-001: boring low-priority notifications may receive a fun fact +FACT-001: low-priority notifications may receive a fun fact FACT-002: critical/legal notifications must never receive a fun fact ``` @@ -734,7 +527,7 @@ plan/ Then execute: ```text -/execute-plan doc/playbook/20260601_fun_fact_notifications +execute-plan doc/playbook/20260601_fun_fact_notifications ``` After implementation, run the normal review: @@ -758,7 +551,7 @@ BLOCK: The spec says legal notifications must never receive fun facts, but there is no fact proving that legal messages are excluded. ``` -That is the point of the workflow: not to generate more documents for fun, but to catch the thing we would otherwise miss. +That is the point of the workflow: not to generate more documents for its own sake, but to catch the thing we would otherwise miss. ## References @@ -767,10 +560,9 @@ This workflow was influenced by these articles on Spec-Driven Development and Fa - [Stop Writing Specs. Start Writing Facts. The Entire SDD Movement Is Already Obsolete](https://medium.com/@wasowski.jarek/stop-writing-specs-start-writing-facts-the-entire-sdd-movement-is-already-obsolete-9045f7061e26) - [Comparing 15 Spec-Driven Development Frameworks](https://medium.com/@wasowski.jarek/comparing-15-spec-driven-development-frameworks-sdd-c052df529274) -## Based on +## Based On Forked and adapted from: - [Karpathy's Claude.md](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) - [Everything-Claude-Code](https://github.com/affaan-m/everything-claude-code) - diff --git a/agents/planner.md b/agents/planner.md index a43baff..4d12713 100644 --- a/agents/planner.md +++ b/agents/planner.md @@ -1,3 +1,10 @@ +--- +name: planner +description: Converts approved SDD inputs into a deterministic implementation plan. Use after spec.md, research.md, delivery_artifacts/*.md, and facts/*.md exist. +model: sonnet +tools: Read, Glob, Grep, Bash, Write +--- + # Planner SDD Addition Add this section to `agents/planner.md`. @@ -105,4 +112,3 @@ Validation: - Run targeted test file. - Run linter. ``` - diff --git a/keybindings.json b/claude-code/keybindings.json similarity index 100% rename from keybindings.json rename to claude-code/keybindings.json diff --git a/settings.json b/claude-code/settings.json similarity index 100% rename from settings.json rename to claude-code/settings.json diff --git a/codex/AGENTS.md b/codex/AGENTS.md new file mode 100644 index 0000000..a0043b0 --- /dev/null +++ b/codex/AGENTS.md @@ -0,0 +1,32 @@ +# AGENTS.md + +OpenAI Codex wrapper for the shared AI coding instructions in this repository. + +## Shared Core + +Read and apply `CORE.md` from this Codex home directory before doing work. It is the source of truth for tool-agnostic behavior: + +- Think before coding. +- Prefer the simplest implementation that solves the request. +- Make surgical changes only. +- Define success criteria and verify results. + +If `CORE.md` is not present, ask the user to reinstall this configuration. + +## Installed Assets + +The installer places shared assets in these locations: + +- Custom Codex subagents: `~/.codex/agents/*.toml` +- Codex global guidance: `~/.codex/AGENTS.md` +- Reusable Codex skills: `$HOME/.agents/skills/*/SKILL.md` +- Shared rule documents: `$HOME/.agents/rules/` +- Legacy prompt wrappers: `~/.codex/prompts/*.md` + +When a skill or agent references `rules/...`, resolve that path from the active project first. If the active project does not contain the referenced rule, resolve it from `$HOME/.agents/rules/`. + +## Codex Differences + +- Use Codex skills through `/skills`, explicit `$skill-name` mentions, or implicit skill matching. +- Use custom agents by explicitly asking Codex to spawn the named agent. +- Prompt wrappers under `~/.codex/prompts/` provide slash-command entrypoints where Codex supports custom prompts, but Codex skills are the preferred reusable workflow surface. diff --git a/codex/README.md b/codex/README.md new file mode 100644 index 0000000..a94e0c3 --- /dev/null +++ b/codex/README.md @@ -0,0 +1,10 @@ +# Codex Adapter Files + +These files adapt the shared configuration repository to OpenAI Codex. + +- `AGENTS.md` is installed to `~/.codex/AGENTS.md` and points Codex at `CORE.md`. +- `config.toml` is a minimal Codex config fragment. +- Codex custom-agent TOML is generated from `agents/*.md` by `scripts/generate-codex-agents.sh` during install. Generated agent files are not checked in, so `agents/*.md` remains the source of truth. +- `prompts/*.md` provides legacy custom prompt wrappers for command-like entrypoints. + +Codex skills are installed from the repository `skills/` directory into `$HOME/.agents/skills`. diff --git a/codex/config.toml b/codex/config.toml new file mode 100644 index 0000000..e313618 --- /dev/null +++ b/codex/config.toml @@ -0,0 +1,14 @@ +# OpenAI Codex configuration fragment for this repository. +# +# Codex reads user configuration from ~/.codex/config.toml and project +# overrides from .codex/config.toml in trusted repositories. + +# Let Codex consume Claude-style project instructions when a repository has +# CLAUDE.md but not AGENTS.md. +project_doc_fallback_filenames = ["CLAUDE.md"] + +# Keep shared guidance and workflow docs from being truncated too aggressively. +project_doc_max_bytes = 65536 + +[features] +multi_agent = true diff --git a/codex/prompts/architecture-decision-records.md b/codex/prompts/architecture-decision-records.md new file mode 100644 index 0000000..70ccc47 --- /dev/null +++ b/codex/prompts/architecture-decision-records.md @@ -0,0 +1,10 @@ +--- +description: Run the architecture-decision-records skill. +argument-hint: [context] +--- + +Use the $architecture-decision-records skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/create-plan.md b/codex/prompts/create-plan.md new file mode 100644 index 0000000..f5a22a9 --- /dev/null +++ b/codex/prompts/create-plan.md @@ -0,0 +1,10 @@ +--- +description: Generate or repair an SDD implementation plan. +argument-hint: [playbook-path-or-context] +--- + +Use the planning behavior from the planner agent and the shared SDD rules to create or repair an implementation plan. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/deep-spec-review.md b/codex/prompts/deep-spec-review.md new file mode 100644 index 0000000..1cd0033 --- /dev/null +++ b/codex/prompts/deep-spec-review.md @@ -0,0 +1,10 @@ +--- +description: Run the deep-spec-review skill. +argument-hint: [path] +--- + +Use the $deep-spec-review skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/execute-plan.md b/codex/prompts/execute-plan.md new file mode 100644 index 0000000..f550881 --- /dev/null +++ b/codex/prompts/execute-plan.md @@ -0,0 +1,10 @@ +--- +description: Run the execute-plan skill. +argument-hint: [plan-path] +--- + +Use the $execute-plan skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/sdd-delivery-artifacts.md b/codex/prompts/sdd-delivery-artifacts.md new file mode 100644 index 0000000..58d30af --- /dev/null +++ b/codex/prompts/sdd-delivery-artifacts.md @@ -0,0 +1,10 @@ +--- +description: Run the sdd-delivery-artifacts skill. +argument-hint: [playbook-path] +--- + +Use the $sdd-delivery-artifacts skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/sdd-facts.md b/codex/prompts/sdd-facts.md new file mode 100644 index 0000000..d10c962 --- /dev/null +++ b/codex/prompts/sdd-facts.md @@ -0,0 +1,10 @@ +--- +description: Run the sdd-facts skill. +argument-hint: [playbook-path] +--- + +Use the $sdd-facts skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/sdd-refine.md b/codex/prompts/sdd-refine.md new file mode 100644 index 0000000..7a9d2b5 --- /dev/null +++ b/codex/prompts/sdd-refine.md @@ -0,0 +1,10 @@ +--- +description: Run the sdd-refine skill. +argument-hint: [playbook-path] +--- + +Use the $sdd-refine skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/sdd-research.md b/codex/prompts/sdd-research.md new file mode 100644 index 0000000..ef261ed --- /dev/null +++ b/codex/prompts/sdd-research.md @@ -0,0 +1,10 @@ +--- +description: Run the sdd-research skill. +argument-hint: [playbook-path] +--- + +Use the $sdd-research skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/sdd-start.md b/codex/prompts/sdd-start.md new file mode 100644 index 0000000..2bb227a --- /dev/null +++ b/codex/prompts/sdd-start.md @@ -0,0 +1,10 @@ +--- +description: Run the sdd-start skill. +argument-hint: [playbook-path] +--- + +Use the $sdd-start skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/codex/prompts/spec-review.md b/codex/prompts/spec-review.md new file mode 100644 index 0000000..5d6156c --- /dev/null +++ b/codex/prompts/spec-review.md @@ -0,0 +1,10 @@ +--- +description: Run the spec-review skill. +argument-hint: [path] +--- + +Use the $spec-review skill for this request. + +Arguments: + +$ARGUMENTS diff --git a/scripts/generate-codex-agents.sh b/scripts/generate-codex-agents.sh new file mode 100755 index 0000000..ac6367f --- /dev/null +++ b/scripts/generate-codex-agents.sh @@ -0,0 +1,102 @@ +#!/usr/bin/env bash +set -euo pipefail + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +repo_root="$(cd "$script_dir/.." && pwd)" +out_dir="${1:-$repo_root/codex/agents}" + +mkdir -p "$out_dir" + +agent_files=( + antagonist + implementer + planner + reviewer + tdd-guide + tech-lead +) + +extract_frontmatter_field() { + local file="$1" + local field="$2" + + awk -v key="$field" ' + NR == 1 && $0 == "---" { in_fm = 1; next } + in_fm && $0 == "---" { exit } + in_fm { + prefix = key ":" + if (index($0, prefix) == 1) { + value = substr($0, length(prefix) + 1) + sub(/^[ \t]+/, "", value) + sub(/[ \t]+$/, "", value) + gsub(/^"/, "", value) + gsub(/"$/, "", value) + print value + exit + } + } + ' "$file" +} + +body_without_frontmatter() { + local file="$1" + + awk ' + NR == 1 && $0 == "---" { in_fm = 1; next } + in_fm && $0 == "---" { in_fm = 0; next } + !in_fm { print } + ' "$file" +} + +first_heading() { + local file="$1" + + awk ' + /^# / { + sub(/^# /, "") + print + exit + } + ' "$file" +} + +toml_escape() { + printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' +} + +for agent in "${agent_files[@]}"; do + src="$repo_root/agents/$agent.md" + [ -f "$src" ] || continue + + if grep -q "'''" "$src"; then + echo "Cannot generate TOML for $src because it contains triple single quotes." >&2 + exit 1 + fi + + name="$(extract_frontmatter_field "$src" name || true)" + description="$(extract_frontmatter_field "$src" description || true)" + + if [ -z "$name" ]; then + name="$agent" + fi + + if [ -z "$description" ]; then + heading="$(first_heading "$src" || true)" + if [ -n "$heading" ]; then + description="Custom Codex subagent adapted from agents/$agent.md: $heading." + else + description="Custom Codex subagent adapted from agents/$agent.md." + fi + fi + + dst="$out_dir/$name.toml" + { + printf 'name = "%s"\n' "$(toml_escape "$name")" + printf 'description = "%s"\n\n' "$(toml_escape "$description")" + printf "developer_instructions = '''\n" + body_without_frontmatter "$src" + printf "\n'''\n" + } > "$dst" + + echo "Generated $dst" +done diff --git a/scripts/install-claude-code.sh b/scripts/install-claude-code.sh new file mode 100755 index 0000000..440f2a2 --- /dev/null +++ b/scripts/install-claude-code.sh @@ -0,0 +1,80 @@ +#!/usr/bin/env bash +set -euo pipefail + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +repo_root="$(cd "$script_dir/.." && pwd)" +timestamp="$(date +%Y%m%d%H%M%S)" + +case "$(uname -s)" in + Darwin|Linux) + user_home="${HOME:?HOME is required}" + ;; + CYGWIN*|MINGW*|MSYS*) + user_home="${HOME:-${USERPROFILE:?HOME or USERPROFILE is required}}" + ;; + *) + echo "Unsupported platform: $(uname -s)" >&2 + exit 1 + ;; +esac + +claude_home="${CLAUDE_HOME:-$user_home/.claude}" + +install_file() { + local src="$1" + local dst="$2" + local dst_dir + + dst_dir="$(dirname "$dst")" + mkdir -p "$dst_dir" + + if [ -f "$dst" ] && ! cmp -s "$src" "$dst"; then + cp "$dst" "$dst.bak.$timestamp" + echo "Backed up $dst to $dst.bak.$timestamp" + fi + + cp "$src" "$dst" +} + +install_dir() { + local src="$1" + local dst="$2" + + mkdir -p "$dst" + cp -R "$src"/. "$dst"/ +} + +verify_path() { + local path="$1" + + if [ ! -e "$path" ]; then + echo "Missing expected path: $path" >&2 + return 1 + fi +} + +echo "Installing Claude Code configuration to $claude_home" + +mkdir -p "$claude_home" + +install_file "$repo_root/CORE.md" "$claude_home/CORE.md" +install_file "$repo_root/CLAUDE.md" "$claude_home/CLAUDE.md" +install_file "$repo_root/claude-code/settings.json" "$claude_home/settings.json" +install_file "$repo_root/claude-code/keybindings.json" "$claude_home/keybindings.json" + +install_dir "$repo_root/agents" "$claude_home/agents" +install_dir "$repo_root/skills" "$claude_home/skills" +install_dir "$repo_root/rules" "$claude_home/rules" +install_dir "$repo_root/commands" "$claude_home/commands" + +verify_path "$claude_home/CORE.md" +verify_path "$claude_home/CLAUDE.md" +verify_path "$claude_home/agents/planner.md" +verify_path "$claude_home/skills/execute-plan/SKILL.md" +verify_path "$claude_home/rules/common/output-budget.md" +verify_path "$claude_home/commands/create-plan.md" +verify_path "$claude_home/settings.json" +verify_path "$claude_home/keybindings.json" + +echo "Claude Code install verified." +echo "Restart Claude Code to reload agents, skills, commands, and settings." diff --git a/scripts/install-codex.sh b/scripts/install-codex.sh new file mode 100755 index 0000000..fd79b59 --- /dev/null +++ b/scripts/install-codex.sh @@ -0,0 +1,95 @@ +#!/usr/bin/env bash +set -euo pipefail + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +repo_root="$(cd "$script_dir/.." && pwd)" +timestamp="$(date +%Y%m%d%H%M%S)" + +case "$(uname -s)" in + Darwin|Linux) + user_home="${HOME:?HOME is required}" + ;; + CYGWIN*|MINGW*|MSYS*) + user_home="${HOME:-${USERPROFILE:?HOME or USERPROFILE is required}}" + ;; + *) + echo "Unsupported platform: $(uname -s)" >&2 + exit 1 + ;; +esac + +codex_home="${CODEX_HOME:-$user_home/.codex}" +agents_home="${AGENTS_HOME:-$user_home/.agents}" + +install_file() { + local src="$1" + local dst="$2" + local dst_dir + + dst_dir="$(dirname "$dst")" + mkdir -p "$dst_dir" + + if [ -f "$dst" ] && ! cmp -s "$src" "$dst"; then + cp "$dst" "$dst.bak.$timestamp" + echo "Backed up $dst to $dst.bak.$timestamp" + fi + + cp "$src" "$dst" +} + +install_dir() { + local src="$1" + local dst="$2" + + mkdir -p "$dst" + cp -R "$src"/. "$dst"/ +} + +verify_path() { + local path="$1" + + if [ ! -e "$path" ]; then + echo "Missing expected path: $path" >&2 + return 1 + fi +} + +echo "Installing OpenAI Codex configuration to $codex_home" +echo "Installing shared skills and rules to $agents_home" + +mkdir -p "$codex_home" "$agents_home" + +install_file "$repo_root/CORE.md" "$codex_home/CORE.md" +install_file "$repo_root/codex/AGENTS.md" "$codex_home/AGENTS.md" + +if [ -f "$codex_home/config.toml" ]; then + install_file "$repo_root/codex/config.toml" "$codex_home/config.claude-shared.example.toml" + echo "Existing $codex_home/config.toml left unchanged." + echo "Review $codex_home/config.claude-shared.example.toml if you want the optional fallback settings." +else + install_file "$repo_root/codex/config.toml" "$codex_home/config.toml" +fi + +"$repo_root/scripts/generate-codex-agents.sh" "$codex_home/agents" + +install_dir "$repo_root/codex/prompts" "$codex_home/prompts" +install_dir "$repo_root/agents" "$agents_home/agents" +install_dir "$repo_root/skills" "$agents_home/skills" +install_dir "$repo_root/rules" "$agents_home/rules" +install_dir "$repo_root/commands" "$agents_home/commands" + +verify_path "$codex_home/CORE.md" +verify_path "$codex_home/AGENTS.md" +verify_path "$codex_home/agents/planner.toml" +verify_path "$codex_home/agents/implementer.toml" +verify_path "$codex_home/prompts/sdd-start.md" +verify_path "$agents_home/skills/execute-plan/SKILL.md" +verify_path "$agents_home/rules/common/output-budget.md" + +if [ ! -f "$codex_home/config.toml" ] && [ ! -f "$codex_home/config.claude-shared.example.toml" ]; then + echo "Missing Codex config or example config under $codex_home" >&2 + exit 1 +fi + +echo "OpenAI Codex install verified." +echo "Restart Codex to reload global guidance, skills, prompts, and custom agents." diff --git a/skills/spec-review/SKILL.md b/skills/spec-review/SKILL.md index ad5186e..097fa20 100644 --- a/skills/spec-review/SKILL.md +++ b/skills/spec-review/SKILL.md @@ -1,3 +1,9 @@ +--- +name: spec-review +description: Lightweight spec review. Reads relevant docs, identifies ambiguity and gaps, asks clarifying questions one at a time, and edits documentation only after decisions are confirmed. +origin: user +--- + # Spec Review 1. Read all spec/operations/security docs in the target directory From 59d3182d380a6054b63d0c8e3eee2b3b65b2da2c Mon Sep 17 00:00:00 2001 From: Leandro Stasi Date: Fri, 5 Jun 2026 13:56:45 +0200 Subject: [PATCH 2/2] Enhance file installation scripts to create timestamped backups for existing files and prevent overwriting non-file paths --- README.md | 2 +- scripts/generate-codex-agents.sh | 23 ++++++++++++++++++++- scripts/install-claude-code.sh | 32 ++++++++++++++++++++++-------- scripts/install-codex.sh | 34 +++++++++++++++++++++++--------- 4 files changed, 72 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 1fbce62..61a998d 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ git pull ./scripts/install-codex.sh ``` -Single-file configs are backed up before replacement when the target file already exists and differs. +Existing files are never silently overwritten. When an installer replaces a changed file, it first creates a timestamped backup next to the original, such as `settings.json.bak.20260605123045`. Directory installs use the same per-file backup behavior. ## Usage diff --git a/scripts/generate-codex-agents.sh b/scripts/generate-codex-agents.sh index ac6367f..d266d24 100755 --- a/scripts/generate-codex-agents.sh +++ b/scripts/generate-codex-agents.sh @@ -4,6 +4,7 @@ set -euo pipefail script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" repo_root="$(cd "$script_dir/.." && pwd)" out_dir="${1:-$repo_root/codex/agents}" +timestamp="$(date +%Y%m%d%H%M%S)" mkdir -p "$out_dir" @@ -64,6 +65,23 @@ toml_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' } +install_generated_file() { + local src="$1" + local dst="$2" + + if [ -e "$dst" ] && [ ! -f "$dst" ]; then + echo "Cannot replace non-file path: $dst" >&2 + exit 1 + fi + + if [ -f "$dst" ] && ! cmp -s "$src" "$dst"; then + cp -p "$dst" "$dst.bak.$timestamp" + echo "Backed up $dst to $dst.bak.$timestamp" + fi + + cp -p "$src" "$dst" +} + for agent in "${agent_files[@]}"; do src="$repo_root/agents/$agent.md" [ -f "$src" ] || continue @@ -90,13 +108,16 @@ for agent in "${agent_files[@]}"; do fi dst="$out_dir/$name.toml" + tmp_file="$(mktemp "${TMPDIR:-/tmp}/codex-agent.XXXXXX")" { printf 'name = "%s"\n' "$(toml_escape "$name")" printf 'description = "%s"\n\n' "$(toml_escape "$description")" printf "developer_instructions = '''\n" body_without_frontmatter "$src" printf "\n'''\n" - } > "$dst" + } > "$tmp_file" + install_generated_file "$tmp_file" "$dst" + rm -f "$tmp_file" echo "Generated $dst" done diff --git a/scripts/install-claude-code.sh b/scripts/install-claude-code.sh index 440f2a2..79c075b 100755 --- a/scripts/install-claude-code.sh +++ b/scripts/install-claude-code.sh @@ -28,20 +28,36 @@ install_file() { dst_dir="$(dirname "$dst")" mkdir -p "$dst_dir" + if [ -e "$dst" ] && [ ! -f "$dst" ]; then + echo "Cannot replace non-file path: $dst" >&2 + exit 1 + fi + if [ -f "$dst" ] && ! cmp -s "$src" "$dst"; then - cp "$dst" "$dst.bak.$timestamp" + cp -p "$dst" "$dst.bak.$timestamp" echo "Backed up $dst to $dst.bak.$timestamp" fi - cp "$src" "$dst" + cp -p "$src" "$dst" } -install_dir() { +install_tree() { local src="$1" local dst="$2" + local path + local rel mkdir -p "$dst" - cp -R "$src"/. "$dst"/ + + while IFS= read -r -d '' path; do + rel="${path#$src/}" + mkdir -p "$dst/$rel" + done < <(find "$src" -mindepth 1 -type d -print0) + + while IFS= read -r -d '' path; do + rel="${path#$src/}" + install_file "$path" "$dst/$rel" + done < <(find "$src" -type f -print0) } verify_path() { @@ -62,10 +78,10 @@ install_file "$repo_root/CLAUDE.md" "$claude_home/CLAUDE.md" install_file "$repo_root/claude-code/settings.json" "$claude_home/settings.json" install_file "$repo_root/claude-code/keybindings.json" "$claude_home/keybindings.json" -install_dir "$repo_root/agents" "$claude_home/agents" -install_dir "$repo_root/skills" "$claude_home/skills" -install_dir "$repo_root/rules" "$claude_home/rules" -install_dir "$repo_root/commands" "$claude_home/commands" +install_tree "$repo_root/agents" "$claude_home/agents" +install_tree "$repo_root/skills" "$claude_home/skills" +install_tree "$repo_root/rules" "$claude_home/rules" +install_tree "$repo_root/commands" "$claude_home/commands" verify_path "$claude_home/CORE.md" verify_path "$claude_home/CLAUDE.md" diff --git a/scripts/install-codex.sh b/scripts/install-codex.sh index fd79b59..c27dd20 100755 --- a/scripts/install-codex.sh +++ b/scripts/install-codex.sh @@ -29,20 +29,36 @@ install_file() { dst_dir="$(dirname "$dst")" mkdir -p "$dst_dir" + if [ -e "$dst" ] && [ ! -f "$dst" ]; then + echo "Cannot replace non-file path: $dst" >&2 + exit 1 + fi + if [ -f "$dst" ] && ! cmp -s "$src" "$dst"; then - cp "$dst" "$dst.bak.$timestamp" + cp -p "$dst" "$dst.bak.$timestamp" echo "Backed up $dst to $dst.bak.$timestamp" fi - cp "$src" "$dst" + cp -p "$src" "$dst" } -install_dir() { +install_tree() { local src="$1" local dst="$2" + local path + local rel mkdir -p "$dst" - cp -R "$src"/. "$dst"/ + + while IFS= read -r -d '' path; do + rel="${path#$src/}" + mkdir -p "$dst/$rel" + done < <(find "$src" -mindepth 1 -type d -print0) + + while IFS= read -r -d '' path; do + rel="${path#$src/}" + install_file "$path" "$dst/$rel" + done < <(find "$src" -type f -print0) } verify_path() { @@ -72,11 +88,11 @@ fi "$repo_root/scripts/generate-codex-agents.sh" "$codex_home/agents" -install_dir "$repo_root/codex/prompts" "$codex_home/prompts" -install_dir "$repo_root/agents" "$agents_home/agents" -install_dir "$repo_root/skills" "$agents_home/skills" -install_dir "$repo_root/rules" "$agents_home/rules" -install_dir "$repo_root/commands" "$agents_home/commands" +install_tree "$repo_root/codex/prompts" "$codex_home/prompts" +install_tree "$repo_root/agents" "$agents_home/agents" +install_tree "$repo_root/skills" "$agents_home/skills" +install_tree "$repo_root/rules" "$agents_home/rules" +install_tree "$repo_root/commands" "$agents_home/commands" verify_path "$codex_home/CORE.md" verify_path "$codex_home/AGENTS.md"