Simple Coding Project

Simple coding project

Takes a small project from idea to a working, documented repository. The user stays in charge of requirements and key design decisions. You do the research, drafting, scaffolding and implementation, and you leave a trail that future agents can pick up (docs/status.md, AGENTS.md).

The phases below run in order. Each phase ends with something the user can review. Don't skip ahead to scaffolding or code before the requirements and design have been reviewed, unless the user explicitly asks you to.

Phase 0: Reconnaissance (before asking anything)

Gather what you can yourself, so the interview asks only what you cannot infer:

• The repo. Read what exists: README, LICENSE, .gitignore, any code. Establish:
  • VCS. .jj means jj; use jj for every write operation, even when it is colocated with git. A plain .git means git. Neither means offer to initialize.
  • Remotes. jj git remote list or git remote -v. Note whether the repo is on GitHub; this matters for CI in Phase 4.
• Referenced material. When the user points at neighboring repos, docs or tools, read the relevant parts: the CLI surface, config formats, security model and extension points. Designs go wrong when they are based on guesses about a dependency.
• Verification. Where possible, check key assumptions empirically: build the dependency, run its CLI, probe edge cases. Record what you verified and how, and label the assumptions you could not verify as such.
• User context. Check memory, CLAUDE.md or AGENTS.md for the user's preferences, such as language, VCS, license, commit style and tooling.

Phase 1: Requirements interview → docs/requirements.md

Interview the user in short rounds of 1–4 related questions. Use the structured question tool if one is available. Give each question a recommended default, and prefer concrete options to open-ended prompts. See references/interview-guide.md for the question bank.

Cover, as relevant:

• the problem and context;
• actors and trust levels;
• goals and non-goals;
• functional requirements;
• security and threat model;
• constraints: language, deployment, dependencies, platforms;
• observability, such as logging and audit;
• future directions to keep in mind without building them now.

When the user has already written a rich brief, don't re-ask what it answers. Draft the document directly and put the gaps in Open questions, each with a proposed answer.

Write docs/requirements.md from references/requirements-template.md:

• Numbered IDs: R1, R2… for requirements; Q1… for open questions; F1… for future enhancements. Later docs and code comments refer to them.
• Resolved questions move into a Decisions table (question → decision) rather than disappearing.
• Deferred ideas go under Future enhancements with enough detail to implement later.

Phase 2: Design → docs/design.md

Sketch the design from references/design-template.md:

• Overview diagram. An ASCII data or control flow is fine.
• Hardest problems first. For each, weigh 2–5 options in a small table and make a clear recommendation; don't just survey. Mark the choice as a decision once the user agrees.
• Contracts and formats. Give concrete examples: config files, file formats, CLI usage, JSON records, error messages.
• A security or failure-mode section when the project touches credentials, sandboxes, or external side effects.
• Testing strategy, repository layout and milestones (M0, M1…), each milestone small enough to finish and verify in one sitting.

Show the user both documents, then iterate:

• Take their answers into the Decisions table.
• Update the requirements and design docs consistently. Grep both for stale references after every change.
• When a decision reverses an earlier approach, rewrite the affected sections instead of appending contradictions. A short note on why the alternative was rejected is still worth keeping.

Commit the docs when the user is happy, or when they ask.

Phase 3: Scaffold the repository

Ask once, as one grouped question with defaults taken from Phase 0, about whatever is still unknown:

• language and toolchain;
• license and copyright holder;
• package or module name;
• whether to use a justfile (default yes).

Then create:

Run just --list and just lint test to confirm the scaffold works before committing.

Phase 4: CI (ask; don't assume)

If the repo has a GitHub remote, or the user plans one, ask whether they want GitHub Actions CI. If yes, add .github/workflows/ci.yml from references/github-ci-template.md. It should:

• run the same entry points as local development (just lint test);
• install just and the toolchain;
• leave out integration tests that need credentials or unusual host features, or put them in a separate, manually triggered job;
• pin action versions.

For non-GitHub remotes, mention that CI can be set up later and move on.

Phase 5: Implement by milestone

For each milestone:

1. Plan the interfaces first. Types and function signatures for each package, so work can be split without conflicts.
2. Write the core yourself, meaning the parts where subtle mistakes are costly: the security-relevant flow and cross-cutting orchestration.
3. Fan out self-contained pieces to subagents on cheaper models when subagents are available and the user is fine with it. Good candidates are leaf packages with a pinned API, test suites and docs. Give each subagent:
   • the exact API spec and the docs to read;
   • a list of the only files it may touch, since other agents run concurrently;
   • instructions not to commit;
   • the verification commands to run;
   • a request to report deviations and bugs prominently.
4. Review every subagent's result. Read the code, rerun its tests, and check its claims against the source. Don't relay reports unverified. Subagent reviews and tests regularly find real bugs in your code, so ask them to look adversarially.
5. Run the full gate (just test-all or equivalent) before committing.
6. Commit in logical changes using the repo's VCS and commit style, for example Conventional Commits. With jj, jj commit <paths> -m … commits a subset while other work is in progress.
7. Update docs/status.md in the same change, plus the README, requirements and design wherever behavior or decisions changed.

When the user steps away and asks you to continue autonomously:

• Make reasonable decisions and record each one, with its rationale, in docs/status.md and the design doc.
• Stop before anything outward-facing: pushing, publishing, or sending anything to external services.

Conventions that apply throughout

• Research before asking. Check the repo and referenced material before asking the user anything.
• Recommend. When presenting options, pick one and say why.
• Verify empirically. When a claim can be tested cheaply, test it and say it was verified.
• Keep docs, code and status consistent. After edits, grep for stale terms such as renamed binaries, old flags and superseded decisions.
• Never push, publish, or change remote state without explicit approval.
• End-of-session summary. Say what was built, what was verified and how, which decisions were made on the user's behalf, which bugs were found, and what remains open.