--- name: better-coding-start description: "Boot the better-coding workflow for a coding session and set up the project folder — load the whole process into working memory and make it durable. Use once at the start of a coding engagement, when adopting these skills in a project, when starting in a new or empty project folder, or when the user says start/boot/set up the coding workflow — even if not phrased that way. Detects the host agent to pick the right file (Claude Code → CLAUDE.md; Codex/Cursor/Windsurf → AGENTS.md), loads the operating procedure, establishes the re-invocation discipline (skills unload — re-invoke before each work package), asks the user's preferred interaction language, installs a durable Coding-workflow block plus optional project info after confirmation, and offers minimal fresh-project scaffolding (git init, .gitignore, README stub, docs/plans). Hands off to /better-coding-orient for the first task. Not per-task routing (orient) and not user Q&A (help). Trigger: /better-coding-start" metadata: version: "2.12.0" license: Apache-2.0 --- # Better Coding Start The boot sequence for the better-coding skill set. A capable agent will use one skill, then drift back to ad-hoc behaviour three tasks later — because skill bodies scroll out of context as a session grows. This skill loads the whole workflow into working memory once, and — crucially — writes a compact version into the project's constitution so it survives context loss. **Primary objective:** the agent operates the full pipeline deliberately for the rest of the session, and re-invokes the right skill before each unit of work instead of relying on a skill still being in context. --- ## Activation Begin the first response after loading with exactly this line: ▸ better-coding-start active — boot the coding workflow Emit it once, then run the steps below. --- ## When to run Run **once per coding engagement**, not per task: - The first substantial coding work in a project, OR - When adopting these skills in a repo, OR - When starting work in a new or empty project folder (see 3d), OR - When the user asks to "start", "boot", or "set up the coding workflow", or to "use the better-coding skills" / "follow the process". If a `## Coding workflow` block already exists in the constitution and this is mid-session, you do not need to run again — the block is doing its job. This skill is **agent-facing session setup**. For a human asking "how does this work?" use `/better-coding-help`; for routing a single task use `/better-coding-orient`. --- ## Step 1 — Load the operating procedure State the pipeline the session will follow: ``` orient (route + explore) → plan (design + tasks) → workflow (implement) → review → verify [+ frontend for UI, + audit for whole-repo/security] when something breaks at any point: debug ``` The ten skills and when each is used: | Skill | Use it when | |-------|-------------| | `/better-coding-start` | Booting the workflow for the session (this skill) | | `/better-coding-orient` | A new/unscoped task arrives, or unfamiliar code must be understood | | `/better-coding-plan` | Designing/speccing a non-trivial feature before code | | `/better-coding-workflow` | Writing or changing any code | | `/better-coding-frontend` | Building or auditing UI | | `/better-coding-review` | Checking a diff/PR before merge | | `/better-coding-audit` | Whole-repo health/security check | | `/better-coding-debug` | Anything broken — bug, failing test, build break | | `/better-coding-verify` | Before claiming done/fixed/passing | | `/better-coding-help` | A human asks how the set works | Standard chains: - **Feature:** orient → plan → workflow [+frontend] → review → verify - **Bug:** debug → workflow → review → verify - **Health check:** audit → plan → workflow → review → verify --- ## Step 2 — Establish the re-invocation discipline State this rule explicitly and follow it for the rest of the session: > **Skills unload. Re-invoke before each unit of work.** > A skill's rules leave the context window as the session grows. Before each > new phase or work package, re-invoke the skill that owns it — do not assume > it is still in context because it loaded earlier. Concretely: - Before **each implementation package** (e.g. each phase from a plan): invoke `/better-coding-workflow` (and `/better-coding-frontend` if the package touches UI). This is the "step 0" that `/better-coding-plan` already writes into every task package. - Before **reviewing**: invoke `/better-coding-review`. - Before **claiming completion**: invoke `/better-coding-verify`. - When **stuck or something breaks**: invoke `/better-coding-debug`. - **Self-check:** the activation line (`▸ better-coding-workflow active — …`) is the loaded-marker. About to write code and no such line is visible in the recent context? The skill has unloaded — reload it before coding. The cost of re-invoking a skill that was still fresh is a few tokens. The cost of *not* re-invoking one that had unloaded is silent drift back to ad-hoc coding — the exact failure this set exists to prevent. --- ## Step 2.5 — Interaction language (ask once) Ask once which language the user prefers for the conversation — offer the language they are already writing in as the default. Honor it for explanations, questions, reports, and summaries. Two boundaries hold regardless of the chosen language: - Code, identifiers, comments, commit messages, and docs stay in **English** (the language convention from `/better-coding-plan`) unless the project's constitution explicitly says otherwise. - The set's fixed markers stay untranslated: activation lines, severity labels (CRITICAL/MAJOR/MINOR/NIT), and checklist wording — they are contract, not prose. If the user wants the preference to be durable, add one line to the instruction file below the workflow block: `Interaction language: [X] (code, comments, and docs remain English).` --- ## Step 3 — Install the durable workflow block (confirm first) The steps above scroll out of context too. The layer that survives is the project's instruction file, which the harness re-injects every turn. Persist the block there. ### 3a — Detect the host agent, then pick the target file Determine which agent is running you and write to the file that host re-injects. Detection signals, in order: 1. **Self-identity** — the system prompt names the product/model: Claude Code or a Claude model → `CLAUDE.md`; Codex/GPT → `AGENTS.md`. 2. **Injected instructions** — a message headed "AGENTS.md instructions for [dir]" means a Codex-style host (`AGENTS.md`); project CLAUDE.md content injected at session start means Claude Code (`CLAUDE.md`). 3. **Directory traces** — `.claude/` → Claude Code; `.codex/` or `.agents/` → Codex; `.cursor/` → Cursor; `.windsurf/` → Windsurf. Cursor and Windsurf follow the open standard → `AGENTS.md`. 4. **Still unsure?** Ask the user one direct question — do not guess. Rules: - If the project already has the matching file, update it. If it has neither, **create the file for the detected host** — a small project instruction file is expected, not intrusive. - If the *other* file also exists (mixed-tool team), offer to mirror the block into it so every tool sees the same workflow. ### 3b — Write the block (confirm first, idempotent) 1. Check whether a `## Coding workflow` block already exists in the file. If it exists and matches the block below, skip to Step 4. 2. **Show the user the exact block you will add** (and say whether you are creating the file or editing an existing one) and ask for confirmation before writing — never edit the constitution silently. 3. On confirmation, insert or update the block — replace an existing `## Coding workflow` section in place rather than appending a duplicate: ```markdown ## Coding workflow (better-coding skills) This project uses the better-coding skill set. Follow this process for all coding work, and re-invoke the relevant skill before each new package or coding section — skills unload as the session grows, so do not assume one is still in context because it loaded earlier. Pipeline: start (boot, once) → orient (route) → plan (design) → workflow (implement) → review → verify. Bug: debug → workflow → review → verify. Whole-repo health/security: audit. UI: pair frontend with workflow. The skills and what each is for: - /better-coding-start — boot the workflow once per session; write/refresh this block - /better-coding-orient — route a new/unscoped task; understand unfamiliar code before changing it - /better-coding-plan — design & spec a non-trivial feature before code; produce the task list - /better-coding-workflow — write or change any code (the engineering discipline) - /better-coding-frontend — build or audit UI: accessibility, UX states, i18n, privacy - /better-coding-review — review a diff/PR before merge (read-only, severity-tagged) - /better-coding-audit — whole-repo health & security check (12 dimensions) - /better-coding-debug — anything broken: bug, failing test, build break (root-cause first) - /better-coding-verify — before claiming done/fixed/passing (evidence gate) - /better-coding-help — explain the set (for humans) Re-invocation rule (skills unload — reload before each unit of work): - Before EACH implementation package or coding section: /better-coding-workflow (plus /better-coding-frontend when it touches UI) - Before reviewing a diff: /better-coding-review - Before claiming done/fixed/passing: /better-coding-verify - When something breaks: /better-coding-debug Self-check: about to write code with no recent "better-coding-workflow active" line in context → the skill has unloaded; reload it first. ``` Keep each skill line to one line — the constitution is re-injected on every turn and Codex truncates instruction files at 32 KiB. This block is the one place the full skill list lives durably; do not expand it into paragraphs or copy detail that belongs in the skill bodies. If `/better-coding-orient` also writes a stack/commands block, the two coexist as separate sections in the same file; do not merge or duplicate. ### 3c — Offer additional project info (optional, ask first) After the workflow block is settled, **ask whether the user wants further project information added** to the same instruction file — the sections that make every later session smarter: Tech stack, Commands (test/lint/build/ format), Conventions, Architecture notes. - If yes: detect what you can from the manifests and the code, ask for the rest in **one batch** (multiple-choice where possible), and write those sections separately below the Coding-workflow block. Apply the earn-its-place test — only what the agent cannot infer from the code. - The section template and detection steps are owned by `/better-coding-orient` Part 2 — invoke it if the host supports invoking skills mid-task; otherwise follow its structure (Tech stack / Commands / Conventions / Architecture). - If no: skip silently. The workflow block alone is a valid boot. ### 3d — Fresh-project scaffolding (offer when the folder is new) If booting in an empty or barely-started folder, **offer** — never do silently — a minimal project setup before the first task: - `git init` plus a stack-appropriate `.gitignore` - a stub `README.md` (project name, one-line purpose, how to run) - `docs/plans/` — where `/better-coding-plan` stores design documents - the instruction file from 3a/3b, if not already written Present it as one multiple-choice offer (e.g. "full setup / git only / skip"). Do **not** scaffold framework or application code — that is implementation work that goes through `/better-coding-orient` routing and `/better-coding-workflow` like any other task. --- ## Step 4 — Hand off Boot is complete. Route the first actual task: - If a task is already in hand → invoke `/better-coding-orient` to size and route it. - If no task yet → state that the workflow is loaded and wait for the task, which will then go through `/better-coding-orient`. Do not start implementing from this skill — it sets up the process; it does not execute it. --- ## Rationalization Prevention | Excuse | Reality | |--------|---------| | "I already know the workflow, no need to boot" | Knowing it and following it under long-context drift are different. The constitution block is what keeps it followed. | | "The workflow skill loaded earlier, it's fine" | It has likely scrolled out. Re-invoke before the package. | | "Writing to CLAUDE.md is overkill" | The block is the only layer that survives compaction. The skill body does not. | | "I'll just route straight to plan" | Fine for one task — but then the session-wide re-invocation habit is never established. | --- ## Relationship to the other skills - `/better-coding-help` — explains the set to a **human**; this skill sets it up for the **agent**. Different audiences. - `/better-coding-orient` — the per-**task** router this skill hands off to. Start runs once per session; orient runs per task. - `/better-coding-plan` — its per-package "step 0: invoke workflow" is the re-invocation discipline this skill generalizes to all work. - `/better-coding-workflow`, `/better-coding-review`, `/better-coding-verify`, `/better-coding-debug`, `/better-coding-audit`, `/better-coding-frontend` — the skills this boot sequence names and schedules for re-invocation.