grain-kit 0.1.9

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

Grain

Structured AI-assisted development with task packets, minimal context, and explicit review gates.

Grain is a CLI-first workflow system for working with coding agents without relying on hidden state, oversized prompts, or loose execution loops.

It gives you:

• 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 CLIs

Grain does not replace coding agents. It gives them a tighter operating system.

---

Why use it

Ad hoc agent-driven development usually degrades into:

• repeated explanations
• broad repo dumps
• context drift across sessions
• inconsistent outputs
• unclear review boundaries

Grain addresses that with a simple rule set:

• 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

---

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

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 use the onboarding prompt:

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.

From there, 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

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.

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.

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

---

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