Configuration: Knots

Knots are the core processing units of Knot. Each knot defines a single processing task: which agent runs, what input to watch, and how to process files.

Knots are .md files with YAML frontmatter inside a loom directory (e.g. rig/prd-review-loom/goals-review.md).

File Format

---
name: goals-review
agent-profile-ref: fast
strand-dir: "project/prds"
---

Review the goals section of this PRD. Check that:
- Each goal is specific and measurable
- Goals align with the problem statement

Frontmatter Fields

Field	Required	Description
name	Yes	Unique knot identifier within its loom. Becomes the KnotId.
agent-profile-ref	Yes	Name of the agent profile to use. Must match a profile in rig/profiles/{name}.md.
strand-dir	Yes	Directory to watch for strand files. Resolved relative to the project root.
git-versioned	No	Whether to create a git commit after each tie-off write. Defaults to true. Set to false to opt out.

Markdown Body

The text after the closing --- is the knot's task-specific instructions. This content is appended to the profile's system prompt at processing time to form the full prompt sent to the agent.

The body must not be empty or contain only whitespace — the parser will reject such files.

Strand Input

Knots accept any text file as strand input — not just .md files. Supported extensions include .rs, .json, .py, .txt, .yaml, and any other text file. Binary files (detected by null bytes in the first 8KB) are silently skipped and logged as StrandIgnored in the loom-log.

This means a knot can process source code, configuration files, or any text-based document.

Directory Resolution

• strand-dir is relative to the project root — the directory containing rig/.
• Absolute paths are also accepted and used as-is.
• Tie-off paths are statically derived: rig/tie-offs/{loom-id}/tie-off-{knot-name}.md

Example Layout

project_root/
├── project/prds/                    ← strand-dir: "project/prds"
└── rig/
    ├── profiles/
    │   └── fast.md
    ├── tie-offs/
    │   └── prd-review-loom/
    │       ├── .loom-log
    │       └── tie-off-goals-review.md
    └── prd-review-loom/             ← loom directory
        └── goals-review.md          ← knot definition

Managing Knots

Check a Knot's Status

Read rig/state.json to see all looms and their knots:

cat rig/state.json | python3 -m json.tool

Each knot entry shows its current processing status (idle, processing, completed, or failed), last processed strand, and tie-off path.

Create a New Knot

Write a .md file inside an existing loom directory:

cat > rig/prd-review-loom/non-goals-review.md << 'EOF'
---
name: non-goals-review
agent-profile-ref: fast
strand-dir: "project/prds"
---

Review the non-goals section for clarity.
EOF

Knot discovers the new file automatically via its file watcher.

Modify a Knot

Edit the .md file directly. Changes are picked up by the file watcher and logged in the loom-log.

Delete a Knot

Remove its .md file:

rm rig/prd-review-loom/non-goals-review.md

Knot discovers the removal automatically.

Alternatively, use the knot-create skill — ask your agent "delete the non-goals-review knot in prd-review-loom".

Multiple Knots Per Loom

A single loom can contain multiple knot files, each watching the same or different strand directories. This is useful when different aspects of the same input need different treatment:

rig/planning-loom/
├── prd-planner.md        ← creates plans from PRDs
├── adr-planner.md        ← aligns plans with ADRs
└── plan-reviewer.md      ← reviews plan quality

All three knots live in the same loom (planning-loom) because they all produce or maintain plans.

Error Handling

Scenario	Symptom	Fix
Profile not found	Knot fails with ProfileNotFound	Create the profile at rig/profiles/{name}.md
Strand dir missing	Knot registers but finds no files	Create the directory or fix the path
Invalid frontmatter	Knot is skipped; KnotParseWarning in loom-log	Check YAML syntax in the .md file
Duplicate knot name	Second knot overwrites first in the loom	Use unique names within each loom
Binary file as strand	StrandIgnored in loom-log	Use a text file, or change the strand-dir

Check the loom activity log to diagnose issues:

cat rig/tie-offs/prd-review-loom/.loom-log