Tutorial: Project Planning

This walkthrough shows how Flint works when the job is not “take random notes,” but “plan and track a real software project without drifting away from the code.”

The example below uses a fictional project called Payments Rewrite, but the pattern is the same for most engineering work.

The Goal

By the end of this walkthrough, you should have a Flint that can:

• point to the real codebase
• hold durable planning notes in Mesh/
• track project work with shards
• publish a clean planning export if needed

More importantly, you will have a workspace where an agent can execute planning-oriented cognitive programs instead of improvising the whole workflow from scratch.

Step 1: Create the Planning Workspace

Start with a new Flint:

flint init "Payments Rewrite" --preset default
cd "(Flint) Payments Rewrite"

Using --preset default is helpful here because planning work usually benefits from having the common project-oriented shards available early. Those shards are the cognitive programs that give an agent reusable planning behavior.

Step 2: Point the Flint at the Real Code

Before writing a lot of planning notes, connect the workspace to the codebase it is actually about:

flint reference codebase "Payments API"
flint fulfill codebase "Payments API" /Users/me/dev/payments-api

This is one of the most important steps in the whole process.

Why?

Because a planning Flint is strongest when it can say, “this note is about that actual system,” rather than becoming a floating layer of abstractions with no source anchor.

Step 3: Add Planning Shards Deliberately

In flint.toml, declare only the shards that support the kind of planning you actually want to do:

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
increments = { source = "NUU-Cognition/shard-increments" }
plan = { source = "NUU-Cognition/shard-plan" }

Then run:

flint sync

This is a good example of Flint’s general philosophy: declare what the workspace should know about, then let the CLI reconcile it. In this case, you are declaring the planning programs the workspace should make available to an agent.

Step 4: Create the First Real Planning Notes

You do not need a huge structure at the start. A strong minimum is:

• one good init note
• one high-level plan note
• one current increment
• one or more task notes

An example structure might look like:

Mesh/
├── (System) Flint Init.md
├── (Plan) Payments Rewrite.md
├── (Increment) 1.0 - API Foundation.md
└── Types/Tasks/

The exact shape depends on your shard conventions, but the principle is stable: keep the planning surface small and readable at first.

Step 5: Write Planning Notes That Point Back to Source

A planning note should never become a substitute for source inspection. It should be a durable thinking layer that points back to source when needed.

Good planning notes often include:

• links to the codebase reference note such as [rf-cb-payments-api](/rf-cb-payments-api)
• file paths or package names when they matter
• explicit assumptions and open questions
• links between planning notes, tasks, and increments

This keeps the planning layer honest.

Step 6: Decide Whether You Need a Workspace Repo

Sometimes the Flint should only reference the main codebase. Other times it should also contain a repo that belongs inside the workspace itself, such as a sandbox, spike repo, or companion service.

If you need that, create a workspace repo:

flint workspace create "Sandbox" git@github.com:me/payments-sandbox.git

This is different from a codebase reference:

• a reference points to something external
• a workspace repo becomes part of the Flint’s own active surface

Use the one that matches reality.

Step 7: Keep the Workspace in Sync with Reality

As planning evolves, flint.toml usually changes too. You may add:

• new shards
• more references
• a new source mesh export
• another workspace repo

Whenever that happens:

flint sync

This becomes part of the normal planning rhythm, not an occasional repair command.

Step 8: Export the Shareable Plan

At some point you may want a planning artifact you can share cleanly with other people.

Pick a root note, tag it with #export, then run:

flint export scan
flint export build

Now the workspace has both:

• the internal planning graph in Mesh/
• the built shareable output in Exports/

That split is powerful because it lets the internal workspace remain detailed while the export stays curated.

Step 9: Use Git as the Planning Cadence

Planning work often changes both notes and workspace config. Flint’s git helper is useful here:

flint git init
flint git sync -m "update planning baseline"

flint git sync is useful because it runs flint sync before the git flow. That helps keep committed state aligned with declared state.

A Healthy Everyday Loop

Once the workspace is established, a good daily loop looks like this:

1. inspect the referenced codebase
2. update plan, task, or increment notes in Mesh/
3. change flint.toml only when the workspace’s declared relationships change
4. run flint sync
5. commit the durable changes

That is the core of source-first project planning in Flint.