roadmap

Files (1)

• SKILL.md

SKILL.md (first lines)

# Implementation Plan Manager

Create or update an `implementation_plan.md` file with Markdown task checkboxes for tracking project tasks. Scale the plan to the request: a simple fix may need one vertical slice and one verification step; a larger project may need phases.

## Anti-slop rules (read first)

A roadmap is a list of *commitments*, not a list of best-practice rituals. Every task you emit must trace to one of:

1. **The spec** (mvp.md, prd.md, brief.md, etc.) — quote or reference the spec line.
2. **Explicit user intent** in this conversation.
3. **A concrete failure** the project has already hit.

If a task doesn't trace to one of those three, it's slop. Common slop patterns to **NOT emit by default**:

- "Set up CI/CD pipeline" — only if the spec requires CI as the venue for something specific (eval harness, anti-goal enforcement, team gating). A solo dev who runs gates manually does not need CI on every merge request or pull request.
- "Add pre-commit hooks" / "husky" / "lint-staged" — friction without payoff for solo projects. Add only when a collaborator-shaped failure has happened (someone pushed broken code).
- "Branch protection on main" — theater on a solo repo. Add only when collaborators land or MR/PR review becomes a real workflow.
- "Set up Dependabot / Renovate" — add only when the spec calls for security posture or dependency rot is an actual concern.
- "Add Storybook" / "Add Sentry" / "Add OpenTelemetry" — add only when the spec or a real failure asks for it.
- "Add monitoring / alerting" — load-bearing for production services, slop for local-first tools.
- "Add compliance process" — add only when the project handles controlled data, customer confidential data, production access, enterprise delivery, or an explicit audit/security requirement.
- "Run every audit skill" — slop unless the project shape calls for it. Pick the narrow gate that controls the actual risk.

**Default to less.** The smallest plan that fully ships beats a large plan that suffocates. If you're unsure whether a task belongs, ask the user instead of emitting it.

## Mandatory simplicity gate

Understand the real flow first, then stop at the first option that fully meets the request:

1. Does this need to exist? If not, skip it.
2. Does the codebase already provide it? Reuse it.
3. Can the standard library provide it? Use it.
4. Can a native platform feature provide it? Use it.
5. Can an already-installed dependency provide it? Use it.
6. Can one direct change provide it? Prefer that.
7. Only then plan the minimum new code that works.

Do not plan speculative abstractions or extensibility, new dependencies, configurable knobs for fixed values, unrelated refactors, scaffolding for future work, redundant fallbacks, hypothetical infrastructure, or compatibility machinery without a real consumer. Trace the real flow and fix shared root causes once instead of planning repeated symptom patches. The smallest complete change wins; code golf, skipped comprehension, and fragile shortcuts do not.

Do not simplify away security, privacy, trust-boundary validation, accessibility, or error handling that prevents data loss.

## Task shape

Every task = one user-visible behavior built end-to-end (UI + logic + data + test). Under 2 days of work. Demoable when done.

No horizontal "set up the database" or "build the API layer" tasks. Those are not tasks — they hide inside a feature task. A real task lands a slice of the product, top to bottom.

Bad task: "Set up the database."
Good task: "Add user signup endpoint that persists to the users table, returns a session token, and has integration test coverage."

If the task is too big to ship in 2 days, split it into thinner vertical slices, not horizontal layers.

## Project shape — ask before planning

Before writing the plan, identify the project shape. Use AskUserQuestion if the answer isn't obvious from the codebase + spec:

- **Solo private-to-public OSS tool** (one dev, no MR/PR review, ships when ready): skip CI-on-MR/PR, skip pre-commit, skip branch protection. Keep distribution + eval + anti-goal guards if the spec calls for them.
- **Team SaaS / production service**: CI, branch protection, monitoring, alerting are load-bearing. Include them.
- **Enterprise / compliance-sensitive repo**: include only the governance gates that match the data and delivery risk: data classification, ADR/risk register, hardening audit, secure code review, release readiness, and MR/pipeline evidence.
- **Internal tool / script**: minimal scaffolding. Skip almost all infra tasks.
- **Library / SDK published to a registry**: include release automation, version tagging, changelog discipline. Skip deploy/infra.

The shape determines which "best practice" tasks are real commitments vs. ritual.

## Repo-first discovery

Before adding any process, tooling, CI, testing, formatting, security, deployment, or release task, inspect how the current repo already works. Existing repo evidence beats generic preference.

Check for:

- Platform and workflow: `git remote -v`, `.gitlab-ci.yml`, `.github/workflows/`, merge/pull request templates, CODEOWNERS.
- Project commands: README, Makefile, package scripts, pyproject, Cargo.toml, justfile, taskfile, tox, nox.
- Existing quality gates: test commands, lint/typecheck commands, coverage config, security scans, dependency checks.
- Existing docs: `CLAUDE.md`, `AGENTS.md`, `.claude/rules/standards.md`,
  matching path-scoped `.claude/rules/**/*.md`, `CONTRIBUTING.md`,
  `SECURITY.md`, ADRs, and runbooks.
- Existing architecture: source directories, tests, migrations, deployment manifests, Dockerfiles, infra files.

Planning rules:

- If the repo already has a gate, use that gate by name instead of proposing a new tool.
- If the repo has no evidence for a tool, do not add it unless the spec, user intent, or known failure requires it.
- If the repo has a lightweight manual workflow that fits the project shape, preserve it.
- If a stronger gate is genuinely required, explain the repo evidence and the risk that justifies adding it.
- If discovery is inconclusive, ask one focused question instead of filling the plan with generic setup tasks.

## CodeGraph blast radius

For structural code questions, use CodeGraph instead of grep when the project has a `.codegraph/` index:

1. Use `codegraph_context` to find the relevant flow, symbols, and definitions.
2. Use `codegraph_impact` on symbols the plan proposes changing.
3. Use `codegraph_callers` or `codegraph_callees` only when more focused call-path detail is needed.
4. Record affected callers, entry points, public contracts, persisted data, and relevant tests in the plan. Do not copy raw tool output into the plan.

Trust CodeGraph results; do not re-verify them with grep. Use `rg` for literal text only. If CodeGraph is not initialized, ask: "I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"

## Platform language

Detect the repository host before writing process tasks:

- GitLab repo: use merge request, pipeline, protected branch, approval rule, environment, project, and group.
- GitHub repo: use pull request, Actions, branch protection, environment, and repository.
- Unknown or platform-neutral: use MR/PR and CI pipeline.

Do not generate GitHub Actions tasks for GitLab repositories. Do not generate GitLab CI tasks for GitHub repositories unless the repo already uses that pattern.

## Compatibility boundary

Backward compatibility is not a default requirement. Do not plan shims, aliases, dual paths, deprecation layers, or migrations for unreleased or internal formats merely to preserve old implementation details. When a clean break is allowed, plan the direct replacement and deletion of the obsolete path.

Compatibility and recovery remain required when supported by evidence:

- persisted user or database data must survive;
- schema and data migrations need safe rollback or recovery where failure can corrupt or strand data;
- explicitly supported public or stable APIs, CLI contracts, file formats, integrations, and user workflows must be preserved or changed through an explicit decision;
- security, privacy, trust-boundary validation, accessibility, and error handling that prevents data loss must not be simplified away.

Every compatibility task must name the real consumer or persisted data, the failure caused by omitting it, and the requirement that justifies it. Otherwise remove the task.

From tcbuilds/nautilus, MIT.

More from tcbuilds/nautilus