--- name: bindify description: Use when the user references wip-docs/, .bindify/, bindify commands, plan/proposal/update/verify artifacts, coordinator workflows, multi-agent execution with shared markdown state, iterate-planning-mode, prototype-mode, verify-worktree, drafting a brief, investigating a feature or fix, looking up prior fixes, or when bindify chat/planning/implementation should follow caveman and ponytail. --- # Bindify Filesystem protocol for AI agents on software work. Active plan docs live in `wip-docs///` at the project root. The tracking repo (`.bindify/` or `bindify/`) holds architecture, migrated plans, and `history/`. Load command and template files from this skill's `references/` on demand. Layout detail: `references/docs/layout.md`. Pipeline diagrams: `references/docs/workflow.md`. ## Three path layers | Layer | Where | Use | |---|---|---| | Skill | This install | Commands + templates | | Active WIP | `wip-docs///` | Write brief/proposal/plan/updates/verify. Coordinator at `wip-docs//coordinator.md` | | Tracking | `.bindify/` or `bindify/` | Read project/architecture; migrate development/ at packaging; history may start at draft PR | Never open tracking looking for skill commands or templates. ## Read by role | Role | Read | |---|---| | **Planner** | `working-style.md`, `draft-brief`, `generate-proposal`, `save-agent-plan`, `publish-plan` (branch stack), wait for ready | | **Executor** | `working-style.md`, `iterate-planning-mode`, `summarize-work-for-updates`, `next_step.py`, `generate-verify` on finish | | **Reviewer** | `review-plan` (build/CI gate + one fixes round) | | **Packager** | `log-pr`, `publish-bindify-pr`, `generate-history-summary` | ## When to invoke each command | User signal | Command | Reference | |---|---|---| | adapt / configure project | `configure-project` | `references/commands/configure-project.md` | | coordinate updates | `coordinate-updates` | `references/commands/coordinate-updates.md` | | capture brief | `draft-brief` | `references/commands/draft-brief.md` | | generate proposal | `generate-proposal` | `references/commands/generate-proposal.md` | | save plan / proposal approved | `save-agent-plan` | `references/commands/save-agent-plan.md` | | /bindify / publish plan | `publish-plan` | `references/commands/publish-plan.md` | | run step / iterate | `iterate-planning-mode` | `references/commands/iterate-planning-mode.md` | | review open plan PR | `review-plan` | `references/commands/review-plan.md` | | prototype | `prototype-mode` | `references/commands/prototype-mode.md` | | verify worktree (macOS) | `verify-worktree` | `references/commands/verify-worktree.md` | | after a step | `summarize-work-for-updates` | `references/commands/summarize-work-for-updates.md` | | scan architecture | `scan-architecture` | `references/commands/scan-architecture.md` | | log PR | `log-pr` | `references/commands/log-pr.md` | | history summary / abandoned | `generate-history-summary` | `references/commands/generate-history-summary.md` | | regenerate overview | `regenerate-overview` | `references/commands/regenerate-overview.md` | | publish bindify PR / package | `publish-bindify-pr` | `references/commands/publish-bindify-pr.md` | | generate verify | `generate-verify` | `references/commands/generate-verify.md` | | investigate / prior fixes | `investigate` | `references/commands/investigate.md` | | research codebase | `research-codebase` | `references/commands/research-codebase.md` | | repair links | `update-links` | `references/commands/update-links.md` | | log hotfix | `log-hotfix` | `references/commands/log-hotfix.md` | | abandon / drop plan | `abandon-plan` | `references/commands/abandon-plan.md` | ## Hard rules - Active docs stay in `wip-docs///` until packaging. Coordinator is `wip-docs//coordinator.md`. Several plans of one feature can sit side by side. Read sibling plan docs before writing a proposal or plan, and again before a step. Do not write active plan artifacts into tracking `development/` during apply. Flat files directly in `wip-docs/` mean stop and ask. - Branch stack: see `publish-plan.md`. A different plan, while on another plan or `plan-fixes` branch of the same feature, is cut from the current tip. Its draft PR still targets `feature/`. Merge that PR with a merge commit. Executors never create branches. Only `review-plan` creates `plan-fixes/`. - One history card per plan. Slug is `-`. Iterations and `plan-fixes` refresh that card. - Packaging migrates and deletes that plan folder only. The feature folder goes away when no plan folders remain. - Never modify existing plan steps during apply. Execution state → `updates.md`. `review-plan` may append steps on `plan-fixes/` only. - Every update entry needs Impact & Connections + Architecture. Append-only for `updates.md` and `hotfixes.md`. - Architecture `Responsibility` is human-owned. `scan-architecture fill` appends change-log lines and edges only — and runs at packaging, not per step. - Package **per plan** on the plan head after sign-off, **before** the plan PR merges into its base. Feature → main is human, outside bindify. History `merged` = plan PR into its base. - Brief ≤ 150 words. Proposal: Primer ≤ 300 words (+ table); Risks ≤ 3 bullets. Primer teaches the technology; project choices are facts in `In this project`. - Prototype-first for user-facing features; Prototype steps carry a human checkpoint. - Repo-relative paths only. No code dumps in context files. - Investigate tracking names/fixes before product code. Clarify before `brief.md`. - Chat is caveman; artifacts stay normal prose. Plan/build with ponytail (`references/docs/working-style.md`). - Blanche owns agent PRs: commits `--author="blanche "`; `gh pr create` via `blanche_gh_token.py` so author is `blanche[bot]`. Missing credentials → stop. See `references/docs/blanche-github-app.md`. - `update-links` runs at `generate-verify` and at migration (plus history/hotfix/architecture writes) — not after every WIP write. ## Two responsibilities | Phase | Document | Who | |---|---|---| | plan / propose / review | brief → proposal | human + AI | | apply | plan + updates | executor via iterate | | verify | verify.md | human checklist | | review | ready plan PR | reviewer via review-plan | | package | migrate + history | packager | | abandon | history abandoned | human-triggered abandon-plan | ## What to read next - `references/AGENTS.md` — drop-in entry for host repos - `references/docs/working-style.md` — clarify, caveman, ponytail - `references/docs/workflow.md` — branch stack visuals, roles - `references/docs/layout.md` — folder trees - `references/docs/blanche-github-app.md` — App token setup - `references/commands/.md` — load before invoking - `references/templates/.md` — when creating artifacts When invoking a command, **read that command file first**.