Skip to content
Fito

Author your first case

This page is the spine of case authoring. Nine steps take you from an empty folder to a case a learner can open, and each one is short here with a page of its own when you want the detail.

Set aside more than one sitting. Steps 1 to 5 are a working session; step 6 is you writing real code, and it takes as long as the code takes.

Two things to know before you start. Fito does not write your case’s source code — it writes the contract around it, and the plan you build the code from. And the case lives in your repository, not in Fito.

Before you begin

Section titled “Before you begin”
  • Fito installed, per Install and prerequisites.
  • A Fito server you can reach.
  • An LLM provider configured in pi, and the pi-subagents package installed. Every step below runs on your subscription.
  • gh, authenticated — run gh auth login. Step 8 creates a repository.

It also helps to have played a case first. Authoring one is much easier when you know what the other end looks like: Play your first case.

1. Set up a working directory

Section titled “1. Set up a working directory”

Work in a directory of your own, not inside the Fito package. Several steps write output folders, and Fito refuses to be written into.

→ Set up a working directory

2. Make sure the knowledge exists

Section titled “2. Make sure the knowledge exists”

A case may only reference knowledge components that Fito already holds. Before you design anything, check that the technology, its major line, and the components you have in mind are all there.

If they are not, that is a separate job and it comes first — the knowledge pipeline, from provisioning a technology through to pushing components.

→ Browse the knowledge area · Provision a technology

3. Design the case

Section titled “3. Design the case”
/fito-case-design "diagnose a broken JSON endpoint" --technology javalin@7

A dialogue settles the scope, the case type, the duration and the toolchain, then grounds every knowledge reference against the live vocabulary. It writes ./case-proposal.md and nothing else.

Take your time on the references. They are the one thing you cannot change later without starting a new case.

→ Design a case

4. Generate the .case/ folder

Section titled “4. Generate the .case/ folder”
/fito-case-generate --dir ~/code/my-case

This turns the proposal into the contract: the fourteen required files, plus a quiz if you designed one. It runs the structural validator until the tree passes, shows you a digest, and commits.

Read the digest properly, including the optional fields it reports as empty. That list is the only time they are ever mentioned.

→ Generate the .case/ folder · Validate the .case/ folder

5. Plan the source

Section titled “5. Plan the source”
/fito-case-plan-source ~/code/my-case

You get two documents under .authoring/: what the source must be, and ordered steps to get there. They cover both the starter state the learner receives and the exemplar solution.

→ Plan the case source

6. Build the source, outside Fito

Section titled “6. Build the source, outside Fito”

This step is not a Fito command. Work through .authoring/source-plan.md in your own harness, with whatever tooling you like.

You are finished when two things are true:

  • The branch case/solution-v1.0.0 exists locally and every rubric gate passes on it.
  • The starter branch matches what starter_state/known_state.yaml promised — the right tests failing, the right errors showing.

Commit everything.

7. Re-validate the finished tree

Section titled “7. Re-validate the finished tree”
/fito-case-generate --dir ~/code/my-case

The same command, and it takes a different path because .case/ is already there. It finalises artifacts.yaml against the now-real tree and earns the fresh attestation the publish carries.

8. Publish

Section titled “8. Publish”
/fito-publish-case ~/code/my-case --repo my-case

You confirm the repository, approve the storefront description a learner reads before enrolling, and the command does the rest: it pushes main, the frozen v1.0.0 branch and tag, and the solution branch, then registers and publishes the case.

You get back a case id and the URL where it is now listed.

→ Publish a case

9. Open it as a learner

Section titled “9. Open it as a learner”
/fito-case-open <case-id>

Do this. It is the only way to see what you actually shipped — the briefing a learner gets, in the order they get it, with the solution out of reach.

Then run /fito-evaluate <case-id> against a deliberately wrong attempt and see whether your rubric says anything useful.

→ Open and work a case

You have a published case

Section titled “You have a published case”

It is discoverable, it scores, and its refs are frozen. Corrections from here follow one of two routes, and which one depends on whether the correction touches the knowledge references.

What’s next

Section titled “What’s next”