Roadmap driven development
Skill Heng-xiu/xiuxiu-agent-skills/skills/roadmap-driven-development
Build or evolve a substantial repository through documentation-first, roadmap-driven, issue-scoped, human-directed AI-assisted development. Use when Codex needs to bootstrap a repository operating system, plan a multi-phase implementation, turn architecture into executable increments, implement one roadmap step or issue, coordinate independent code review, process review findings with judgment, run codebase-wide quality waves, or preserve a traceable issue-to-merge audit trail.From its SKILL.md
npx -y skills add Heng-xiu/xiuxiu-agent-skills --skill roadmap-driven-developmentAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.9 KB, as published. Nobody here has run it
Roadmap-Driven Development
Treat structure as the mechanism that makes AI implementation reliable. Keep the human responsible for product intent, architecture, scope, and trade-offs; use agents for bounded implementation, investigation, testing, and independent review.
Read references/playbook.md before bootstrapping or redesigning the workflow. Read references/dotllm-case-study.md when explaining the method, adapting it to a difficult systems project, or checking whether the workflow has drifted from its source principles.
Establish the operating system
Inspect the repository before proposing process changes. Reuse existing conventions where they are effective.
Create or strengthen only the artifacts the repository needs:
- Write a repository constitution such as
AGENTS.mdorCLAUDE.md.- State the project identity, architectural invariants, dependency direction, coding rules, validation commands, and prohibited shortcuts.
- Record decision rationale, not merely preferences.
- Route agents to detailed subsystem documents instead of duplicating them.
- Write subsystem design documents for decisions that implementation agents must not improvise.
- Cover boundaries, data flow, interfaces, constraints, failure modes, references, and unresolved questions.
- Require the relevant document to be read before touching that subsystem.
- Write a dependency-aware roadmap.
- Start with the thinnest end-to-end proof.
- Make each step fit one focused implementation session and one reviewable change.
- Give every step a goal, scope, dependencies, likely files, acceptance criteria, and validation checkpoint.
- Preserve identifiers when reordering steps so issues, branches, and commits remain traceable.
Do not create documentation to simulate certainty. Mark hypotheses, unresolved architecture choices, deferred work, and blocked experiments explicitly.
Plan one executable increment
Never begin a substantial increment from a vague request.
- Locate the roadmap step or issue and verify its dependencies.
- Read the repository constitution, relevant design documents, current implementation, tests, and recent history.
- Resolve architectural choices before implementation. Compare external references or prototypes when the choice is consequential.
- Establish the baseline before performance or reliability work.
- Draft an issue with:
- problem and intended outcome;
- in-scope and out-of-scope work;
- dependencies and affected boundaries;
- acceptance criteria;
- test, benchmark, or reproduction method;
- documentation updates required.
- Draft a concrete implementation plan mapping every acceptance criterion to code and validation.
- Present consequential decisions and the plan for human approval before modifying code.
Split the increment if it crosses unrelated concerns, cannot be reviewed coherently, or introduces architecture not already approved.
Implement inside the envelope
Use one issue, one branch, and one pull request unless the repository already has a stronger equivalent.
- Create the issue branch using the repository convention.
- Implement in small logical units.
- For correctness-sensitive optimized code, build the simple reference path and tests before the optimized path.
- Verify after each meaningful unit; do not postpone all feedback until the end.
- Benchmark before and after performance changes under comparable conditions.
- Update the roadmap, design documents, examples, and user documentation when behavior or status changes.
- Stop and return to planning when evidence invalidates an architectural assumption.
Do not let the implementation agent silently widen scope, invent new abstractions, or declare an unverified result complete.
Review with role separation
Do not rely on the implementing agent as the sole reviewer.
- Run the repository's deterministic checks first.
- Give independent reviewers the issue, diff, relevant design documents, and raw test or benchmark evidence.
- Ask reviewers to search for correctness, security, concurrency, resource lifetime, contract, performance, and test gaps as applicable.
- Prefer reviewers with different strengths or models; overlapping findings are not the goal.
- Triage every finding as:
- accept now;
- reject with technical rationale;
- defer to a named issue;
- investigate with a reproduction or measurement.
- Obtain human approval for the disposition before changing code when findings alter scope or architecture.
- Apply accepted fixes, rerun relevant validation, and reply with the exact fix and commit or evidence.
Preserve the PR discussion as an audit trail from finding to disposition to verified change.
Run quality waves
After a milestone or before a public release, suspend feature cadence and review the whole codebase in prioritized waves.
Suggested order:
- P0 security, data-loss, crash, and resource-lifetime risks.
- P1 correctness, concurrency, and cross-module consistency.
- Public presentation: dead code, misleading claims, samples, stubs, and documentation.
- Boundary hardening: validation, API behavior, error handling, and operational safety.
- Specialized performance waves driven by profiling and benchmarks.
Group raw findings into focused issues. Skip waves whose prerequisites do not exist; record why instead of forcing premature work.
Change cadence when the problem changes
Use the issue-plan-implement-review cadence for architecture that is understood and work that can be specified.
Switch to an experiment loop when the unknown is fundamental:
- State the competing hypotheses.
- Design the smallest discriminating benchmark, prototype, trace, or disassembly check.
- Record the environment and result.
- Update the design decision and roadmap.
- Resume implementation only when the evidence supports a direction.
Do not bury research uncertainty inside a feature issue.
Completion gates
Call an increment complete only when:
- acceptance criteria map to verified evidence;
- required tests, builds, linters, and benchmarks pass;
- the diff respects architectural invariants;
- review findings have explicit dispositions;
- documentation and roadmap status match reality;
- deferred work has an owner or issue;
- the PR tells a coherent story from intent through validation.
Report gaps and uncertainty before successes.