Home

harnessed documentation

harnessed is a host-native Python CLI that assembles and launches AI-agent container stacks from declarative recipe/agent/service/stack YAML. This wiki holds the project's guides, design docs, and planning notes. In a main repo checkout it appears as docs/ — an unpinned live clone of this wiki, gitignored rather than a submodule, so there is no pinned commit and no pointer-bump PR. Refresh it with git -C docs pull.

Start here

• ARCHITECTURE — repo layout, the agent/recipe/service/stack/catalog vocabulary, the host-native build/launch model, and the capability-test oracle. Read this first.
• CONTRIBUTING — dev setup and how to add a recipe / agent / service / stack.
• AGENTS.md — operational notes for AI assistants working on this repo.
• harnessed-design — the deeper rationale behind the architecture (the why).

Guides (how-to)

• Recipe authoring
• Service authoring
• Stacks
• Extending stacks (proposed)
• Recipe catalog
• System prompt & rules (proposed)
• Secrets (varlock + 1Password)
• Beads (issue tracking)
• AWS SSO credentials in containers
• Pulumi (host login forwarding)
• Egress firewall & exposing services
• Container filesystem layout
• Git hooks
• Troubleshooting
• Pin management (harnessed update)

Codebase map

Generated by /map-codebase — the where the code lives, how it's written, what's wired to what reference. Regenerate periodically rather than hand-editing.

• ARCHITECTURE · STRUCTURE · CONVENTIONS · INTEGRATIONS · STACK · TESTING · CONCERNS

Planning & roadmap

• Open work: bd ready / bd list --status=open (this project's issue tracker, not a wiki doc).
• done/ — closed-out planning docs kept for an audit trail. The wiki has no directory listing; each is its own page (e.g. 2026-06-29-startup-hooks).

Research & prompts

• research/ — investigation notes (home-folder requirements per harness, etc.), browsable on the wiki
• prompts/ — reusable prompt templates (e.g. recipe-authoring-prompt.md), browsable on the wiki
• recipe-build-findings — accumulated findings from building/debugging recipes

Editing this wiki

This wiki is the source. Edit it via the wiki UI, or by cloning git@github.com:drmikecrowe/harnessed.wiki.git (which is exactly what a main-repo checkout's docs/ already is) and pushing. There is no submodule pointer to bump — a main-repo checkout picks changes up with git -C docs pull.

The wiki publishes pages under a flat namespace: guides/beads.md on disk is served at /wiki/beads, so a relative link like guides/beads.md breaks once rendered here. Run mise run docs in the main repo to rewrite links to their absolute form and to check this page's guide list against the files on disk.