grain-kit 0.1.11

CLI-first workflow toolkit for structured AI-assisted software development.

Grain

Deterministic workflow for agent CLIs.

Grain is a workflow layer for Codex, Claude Code, and similar agent CLIs. It gives coding agents explicit task packets, minimal context, and review gates so development stays structured, inspectable, and repeatable.

It gives agents:

• task packets as the unit of execution
• file-backed workflow state
• minimal context assembly per task
• explicit execute, review, and close gates
• stable prompt entrypoints for agent-driven work

Grain does not replace coding agents. It gives them structure.

---

Why Grain exists

Ad hoc agent-driven development usually degrades into:

• repeated explanations
• oversized repo context
• hidden state across conversations
• context drift across sessions
• inconsistent outputs
• unclear review boundaries

Grain makes the workflow explicit:

• one task packet at a time
• only load the context the task needs
• keep state in repo files
• require explicit review before closure

Mental model:

Idea -> Task Packet -> Context -> Execute -> Review -> Close

This is most useful when you are already working inside an agent CLI and want the agent to follow a deterministic workflow instead of an open-ended conversation.

---

How it is used

Grain is meant to be used through an agent CLI.

The operating loop is:

grain workflow next -> grain prompt show -> agent executes one step -> review -> close

Use Grain to determine the next legal step. Use the agent CLI to carry it out.

---

What Grain manages

Grain separates work into a few visible layers:

• docs/canonical/
  • source-of-truth project decisions
• docs/working/
  • backlog, current focus, open questions, proposals
• docs/runtime/
  • workflow rules, adapter profiles, context-loading rules
• tasks/
  • one folder per task packet
• prompts/
  • stable prompt files for your agent CLI

The workflow is file-backed and inspectable. There is no hidden daemon, database, or background service.

---

Install

Requirements:

• Python 3.11+
• uv recommended, pip supported

Install from PyPI:

uv tool install grain-kit

or:

pip install grain-kit

For local development:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify:

grain --version

---

Quick start

Grain has two real entry paths today:

• start a new repo with grain init
• add Grain to an existing repo with grain onboard

In both cases, the intended operator is an agent CLI:

1. run the Grain command
2. ask Grain for the next workflow step
3. open the recommended prompt in the agent CLI
4. let the agent work inside the Grain loop

New project

mkdir my-project && cd my-project
git init
grain init

That creates the baseline Grain structure:

docs/canonical/
docs/working/
docs/runtime/
tasks/
prompts/

Then start onboarding through your agent CLI:

grain workflow next
grain prompt show

Open prompts/workflow.onboard.new.md in your agent CLI, fill in the project context section, and let the agent generate the initial docs and backlog.

After onboarding, the normal loop is:

grain workflow next
grain prompt show

Then run the recommended prompt in your agent CLI, review the repo changes, and continue through execute, review, and close.

Existing project

cd your-existing-project
grain onboard
grain workflow next
grain prompt show

Then open prompts/workflow.onboard.existing.md in your agent CLI. That prompt is intended to scan the existing repo, draft the canonical docs, and identify open questions. Review those docs before treating them as authoritative.

---

Using Grain with agent CLIs

Grain is designed to be used through an agent CLI such as Claude Code or Codex.

In practice, the agent should use Grain as the workflow layer for the repository:

• use grain commands to determine the next legal step
• use prompt files under prompts/ as stable workflow entrypoints
• operate within the execute, review, and close loop
• respect explicit review and closure gates

The CLI is the delivery surface. The product value is the workflow structure it gives the agent.

Example instruction for an agent:

You have access to the Grain CLI.

Use Grain to onboard this repository and follow the workflow.
Always use Grain commands to determine the next workflow step.
Use the prompt files Grain recommends.
Respect review and closure gates before marking work complete.

Recommended agent instruction

If you want the agent to operate strictly through Grain, use a stronger instruction like this:

You are operating inside a repository that uses Grain as its workflow system.

Your role is to execute work through Grain's state-driven workflow.

Rules:
- Run `grain workflow next` before deciding what to do.
- Run `grain prompt show` before executing the next step.
- Follow the recommended prompt exactly.
- Work on only one active task packet at a time.
- Do not bypass review or closure gates.
- Do not modify canonical docs directly.
- Do not invent workflow steps outside Grain.

If you take action without first calling `grain workflow next`, you are operating incorrectly.

That instruction matches the real usage model well:

• Grain decides the next legal step
• the agent carries out the current step
• review and close remain explicit gates

That keeps agent-driven work:

• structured
• lower-context
• inspectable
• repeatable

The daily loop

The practical loop is:

1. Ask Grain what the next legal action is.
2. Run the recommended prompt in your agent CLI.
3. Review the proposed work.
4. Close the task only when the packet is complete.

That is the main operating model for the app today.

Typical commands:

grain workflow next
grain prompt show
grain review check --id TASK-0001
grain task close --id TASK-0001

If you want Grain to execute one legal state transition and stop at gates:

grain workflow run

If you want repeated state-driven execution:

grain workflow loop --steps 3

Grain controls:

• what happens next
• what context is valid
• when execution stops

The agent controls:

• executing the current step correctly

Onboarding flow

Onboarding is one of the most important workflows in Grain because it gives the agent the initial structure it will follow later.

For a new repo:

grain init
grain workflow next
grain prompt show

Then run the recommended onboarding prompt in your agent CLI.

For an existing repo:

grain onboard
grain workflow next
grain prompt show

Then run the recommended onboarding prompt in your agent CLI.

The onboarding goal is to establish:

• canonical docs
• working docs
• the current backlog shape
• the next valid task flow

Review onboarding output before treating it as project truth.

---

Task packets

A task packet is the unit of execution. Each task lives in its own directory under tasks/.

That includes small fixes and hotfixes. Grain does not have a separate packetless patch mode today:

• if you want the change tracked by Grain, give it a packet
• if the fix is tiny, keep the packet small and use grain task close --quick for low-overhead closure

Packet files include:

• task.md
• context.md
• plan.md
• deliverable_spec.md
• results.md
• handoff.md when needed

Useful commands:

grain task list
grain task show --id TASK-0001
grain task prepare --id TASK-0001
grain task validate --id TASK-0001

To create a packet directly:

grain task create --phase 3 --task-num 4 --title "Add packet validator"

Example small-fix flow:

grain task create --phase 3 --task-num 5 --title "Fix CLI help typo"
grain workflow next
grain prompt show
grain task close --id TASK-0002 --quick --summary "Fixed the CLI help typo."

---

Context control

Grain is built around minimal context loading instead of dumping the whole repo into every interaction.

Build or inspect the context bundle for a task:

grain context build --id TASK-0001
grain context show --id TASK-0001
grain context export --id TASK-0001

The context system can also include selected working docs and adapter-specific hints when relevant.

---

Review and closure

Grain keeps review explicit.

Use:

grain review check --id TASK-0001
grain review summary --id TASK-0001
grain review handoff --id TASK-0001
grain task close --id TASK-0001

The goal is simple: intelligence may propose changes, but closure should be deliberate and inspectable.

---

Adapters

Grain uses adapters to tune context selection and review focus for different types of work while keeping the workflow loop the same.

Current adapter surface includes:

• code_adapter
• frontend_adapter
• docs_adapter
• spreadsheet_adapter

Inspect adapters with:

grain adapter list
grain adapter show --id code_adapter

---

Orchestration

Grain can also generate plan proposals for larger scopes without silently mutating the repo plan.

grain orchestrate scope --scope "Add authentication system"
grain orchestrate plan --scope "Add authentication system"
grain orchestrate accept --plan OP-XXXXXXXX

These outputs are proposals. They are meant to support sequencing, not bypass review.

---

What Grain is not

Grain is not:

• a coding model
• a GUI project manager
• a hidden orchestration service
• a database-backed autonomy layer

It is a disciplined filesystem-first workflow layer for agent-assisted work.

---

Troubleshooting

If grain is not found after install:

uv tool dir --bin

Add that directory to your PATH.

If you hit Python version issues, use Python 3.11+ and reinstall with the interpreter you intend to use.

If you want a local editable install, prefer a dedicated virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

---

Feedback

Issues and feedback:

https://github.com/Diwata-Labs/Grain/issues