reactive.org enterprises ctrl-freaq.ai

GETTING STARTED

From a rough idea to a planned first story.

This is a real run: ask-the-docs, a small open-source tool that indexes a codebase's docs for coding agents. Below is everything the operator typed and decided, and what Claude handed back, in one session.

Prompts are lightly trimmed. Everything Claude filed is public on GitHub, so you can check it against the screenshots.

  1. 01

    Workshop the idea into a PRD

    YOU

    Help me prepare a minimal Product Requirements Document (docs/prd.md) for this project. The seed idea is a small local service that developers run, pointing at their codebase's document folder (e.g. docs/), that indexes the documents it finds in Elasticsearch … The intended audience is developers with coding agents. Help me workshop the idea; I'd like to start with a minimal viable product so I can test the concept.

    CLAUDE

    Asks four scoping questions on one card, each with a recommended answer.

    SearchWhat kind of search should the MVP test?
    • Lexical (BM25) recommended
    • Hybrid
    • Semantic only
    RuntimeWhich language and runtime for the service and CLI?
    • Python recommended
    • TypeScript/Node
    • Go
    ES lifecycleWho manages the Elasticsearch container?
    • Tool ships compose recommended
    • Tool runs container
    • Bring your own ES

    + one more on how the doc catalogue shapes indexing

    YOU three follow-ups, condensed

    Given how heavy Elasticsearch is … we'll need to support indexing multiple codebases. I'd like the tool to be configured via a YAML file … and to query it for metadata, like “which documents are relevant to topic XYZ”.

    Result docs/prd.md, committed and merged to main.

  2. 02

    Workshop the architecture

    YOU

    Now let's workshop an architecture for the service, documented at docs/architecture.md. How do you think it should work?

    CLAUDE
    ProcessHow do reads stay fresh, and is there a daemon?
    • Direct + lazy sync recommended
    • Direct + watcher only
    • Local daemon + API
    YOU typed instead of picking

    Direct + lazy sync sounds interesting, but I'm concerned about indexing time. Some of the documents are large (over a megabyte). I'd want to keep the watch concept but make it optional. Thoughts?

    CLAUDE

    Comes back with a revised design: an optional watcher, a time-budgeted lazy sync, a manual atd sync, and splitting oversized sections, plus the PRD edits to match. One card: Yes, as proposed.

    Result Architecture docs in a hub-and-spoke layout, and a doc catalogue so every later stage treats the PRD and architecture as binding.

  3. 03

    Draft the epic

    YOU 
    /github-pipeline:drafter prepare an epic to deliver the initial implementation with the aim of being able to verify the concept in a real-world project, focus mostly on the "happy path"
    CLAUDE

    Reads the binding docs, then asks before it commits to anything:

    DeferHappy path first: which PRD requirements should this epic defer to the hardening pass?
    • atd prune + orphan flags
    • Detailed config errors
    • Live catalogue refresh
    • Auto rebuild on change
    PrivacyThe architecture puts eval question sets in this public repo, but they'd hold proprietary content. How should I fix that?
    • Update the architecture doc now recommended
    • Note it in the epic only

    + creating the repo, accepting provisional answers to five open questions, and a final “file it?” check

    GitHub issue #1, Epic: Happy-path MVP to test ask-the-docs on a real codebase, labelled enhancement and planned, with its Goal section.
    Epic #1, filed with a goal, background, definition of done and explicit out-of-scope list.
    HANDOFF

    Next: cut #1 into stories in a fresh session.

    /github-pipeline:slicer 1
  4. 04

    Slice it into stories

    YOU 
    /github-pipeline:slicer 1
    CLAUDE

    Proposes eight independently shippable stories in build order, and writes nothing until you approve the whole cut.

    Write gateFile these 8 stories under #1, in this order?
    • File all 8
    • Change the cut
    The epic's Sub-issues panel listing eight stories, #2 to #9, from the technical foundation to finalising the MVP.
    Filed as native GitHub sub-issues, so the epic's progress rolls up as stories close.
  5. 05

    Plan the epic

    YOU 
    /github-pipeline:planner 1
    CLAUDE

    Pins only what crosses stories: who owns each module, the shared contracts and the sequencing. One call is yours:

    DecisionWhat minimum Python version should atd require?
    • Python ≥ 3.12 recommended
    • Python ≥ 3.14

    Recommendations are only defaults: here the operator overrode one, and the plan records it as [user decision 2026-10-24].

    The epic's implementation-plan comment on GitHub, opening with its Approach: eight stories that each ship through their own PR, ordered to retire risk first.
    The epic plan, posted to #1 after two independent review passes.
  6. 06

    Plan the first story

    YOU 
    /github-pipeline:planner #2
    CLAUDE

    Spots that the binding architecture and the story order disagree, and asks rather than guessing:

    DeviationThe architecture points the atd command at a module that story #3 owns. Point it at a placeholder until #3 lands?
    • Approve recommended
    • Reject: re-plan
    Story #2's implementation-plan comment on GitHub, with its Approach for the Elasticsearch-free foundation modules.
    Story #2's plan, with the approved deviation recorded and the date it was agreed.
    HANDOFF

    Next: implement the story in a fresh session.

    /github-pipeline:resolver #2

FROM HERE

The team takes it the rest of the way.

The resolver builds #2 in its own worktree and opens a PR, looping with review until it's clean. The evaluator checks it against the issue and merges it. Then the next story is planned, built and merged the same way. Point a coordinator at the epic and it runs that loop for you, asking only when a call is yours.

Install ctrl-freaq Browse the ask-the-docs issues