hone-ai

hone-ai

AI Coding Agent Orchestrator — Automatically implement features from requirements using AI agents.

Transform feature ideas into working code through autonomous development with human oversight.

Why

When working on long running tasks with agents, their context window fills up and the performance degrades. To mitigate this, hone-ai provides a solution starting each new iteration with a fresh context window just passing in a summary of the progress made so far on the specific PRD, repository architecture and gotchas, and any other relevant information.

Everything else is stripped away, leaving only the essential information needed for the next iteration. This approach helps maintain optimal performance and reduces the likelihood of context drift.

It's a surprisingly powerful process.

Quick Start

Install hone as a native Claude Code plugin:

/plugin marketplace add oskarhane/hone-ai
/plugin install hone@hone-ai

To update:

/plugin marketplace update hone-ai

That's it! You're ready to use hone.

Common Workflow

# 1. Generate project documentation (if no AGENTS.md exists). A one time thing.
/hone:agents-md

# 2. Create a PRD from your feature description
/hone:prd "Add user login with email and password"

# 3. Manually review the generated PRD
#    Edit .plans/prd-user-login.md as needed

# 4. Generate tasks from the PRD
/hone:prd-to-tasks .plans/prd-user-login.md

# 5. (Optional) Extend PRD with additional requirements
/hone:extend-prd .plans/prd-user-login.md "Add two-factor authentication"

# 6. Implement the feature
/hone:run .plans/tasks-user-login.yml -i 10

# 7. Archive completed features (optional)
/hone:prune

hone will implement the feature, run tests, and commit changes automatically.

Skills

All skills are invoked via /hone:<skill-name>.

Workflow

Skill	Description	Example
/hone:init	Initialize hone in current directory	/hone:init
/hone:agents-md	Generate AGENTS.md project docs	/hone:agents-md --overwrite
/hone:prd	Generate PRD from feature description	/hone:prd "Add user authentication"
/hone:prd-to-tasks	Generate task YAML from PRD	/hone:prd-to-tasks .plans/prd-user-auth.md
/hone:extend-prd	Add requirements to existing PRD	/hone:extend-prd .plans/prd-user-auth.md "Add OAuth"
/hone:run	Execute implement/review/finalize loop	/hone:run .plans/tasks-user-auth.yml -i 5

Info

Skill	Description
/hone:status	Show incomplete task lists with progress
/hone:prds	List all PRDs with status
/hone:prune	Archive completed PRDs (--dry-run to preview)

Concepts

A Feature

A feature has three files:

• prd-<feature>.md - Feature description, goals, non-goals, and acceptance criteria.
• tasks-<feature>.yml - A task breakdown of the prd. Description, status, dependencies, and most important, acceptance criteria for each task.
• progress-<feature>.txt - A continuously updated progress report on description of what has been done, choices made for each task etc.

To create a feature, use /hone:prd "<description or link or file>". To break down a PRD into tasks, use /hone:prd-to-tasks .plans/prd-<feature>.md.

Implementation loop

The implementation loop is a continuous process of iterating over the tasks in a feature's tasks-<feature>.yml file. This is the most important part: every iteration starts with a new agent invocation, i.e. a new agent context.

This also means that you can work some time on a feature, switch to a different feature and get back to the old one without polluting the context or have the agent digress over time.

The agent context is initialized with 3 files (plus directions via the prompt):

• tasks-<feature>.yml
• progress-<feature>.txt
• AGENTS.md - information on how to run feedback loops in here, extremely important!

The tasks file has a link to the PRD file so the agent knows how to find it if needed.

The Agent decides what task to work on in each iteration of the loop.

Implementation has three stages: