agent-context

Shared Agent Context

Work Attribution

The orchestrator always provides the work item ID in your task prompt (e.g., "Feature: feat-580dc00b"). Use it:

wipnote feature start <id>   # or bug start / spike start

Rules:

1. Look for a feature/bug/spike ID in the task prompt first
2. If found, run start on it — do NOT create a new one
3. Only create a new work item if the prompt genuinely contains no ID
4. If wipnote is unavailable, proceed — attribution is not a blocker

Work Completion

When your task is done and quality gates pass:

1. Run wipnote feature complete <id> (or bug complete, spike complete)
2. Do this BEFORE reporting back to the orchestrator
3. If the CLI is unavailable, report completion — the orchestrator will handle it

Safety Rules

FORBIDDEN: Never edit .wipnote/ files directly. Use the CLI:

• wipnote feature complete <id> not Edit(".wipnote/features/...")
• wipnote bug create "title" --track <trk-id> not Write(".wipnote/bugs/...")

Bugs require an owning track: use wipnote relevant "<topic>" or wipnote track list to find one before creating the bug. --standalone is supported for feature creation only, not bug creation.

BATCH wipnote CLI calls. Each Bash tool call spends one turn from the user's quota. Chain commands with && into a single invocation whenever possible. Do this (1 call):

wipnote bug create "A" --track trk-xxx && \
wipnote bug create "B" --track trk-xxx && \
wipnote link add feat-aaa bug-new --rel caused_by

Never 3 separate Bash calls for the same thing. Only break into multiple calls when a later command must parse the output (e.g., a returned ID) of an earlier one.

Plan YAML Updates

Plan YAML files (.wipnote/plans/*.yaml) are validated assets — never write them directly. Use the CLI to ensure valid structure:

• Create: wipnote plan create-yaml "<title>"
• Update: wipnote plan rewrite-yaml <plan-id> --file /tmp/updated.yaml
• Validate: wipnote plan validate-yaml <plan-id>

The rewrite-yaml command validates schema, checks meta.id match, and writes atomically. Agent workflow: read plan → modify in memory → write to temp file → call rewrite-yaml.

Development Principles

• DRY — check for existing utilities before creating new ones
• SRP — one purpose per function/module
• KISS — simplest solution that satisfies requirements
• YAGNI — only implement what is needed now
• Module limits: functions <50 lines, files <500 lines
• Research existing libraries/packages before implementing from scratch
• Check project dependencies before adding new ones

These principles are language-neutral and apply to any codebase.