Coach

Coach

IMPORTANT: Start your response by telling the user:

Coach — Explains any Attune topic with progressive depth — concept, then how-to, then full reference.

How It Works

Each depth level serves a different type of content, not just more of the same:

Level	Type	What you get
0	Concept	What is it? When to use it?
1	Procedural	Step-by-step: how to run it
2	Reference	Full detail, edge cases, links

Repeated calls on the same topic auto-advance. A new topic resets to concept.

Commands

Topic Lookup (default)

If the user provided a topic, call:

help_lookup(topic="<topic>", mode="progressive")

Use the bare topic slug — the engine resolves the right template type at each level:

User says	Topic slug
security audit	security-audit
code review	code-review
code quality	code-quality
bug predict	bug-predict
test gen	test-generation
release	release-prep
refactor	refactor-plan
doc gen	doc-gen

If the user says "tell me more" or "go deeper" without a new topic, call help_lookup with the same topic again — it auto-advances to the next level.

If the user says "start from the beginning" or "reset", call:

help_lookup(topic="<topic>", mode="progressive", reset=true)

If the user just finished a workflow, use last_workflow to skip the concept and start at procedural:

help_lookup(
    topic="<topic>",
    mode="progressive",
    last_workflow="<workflow-name>"
)

For file-based warnings:

help_lookup(
    topic="warnings",
    mode="precursor",
    file_path="<path to file>"
)

Init (/coach init)

Bootstrap a project-local help system. Two-step Socratic flow using the help_init MCP tool.

Step 1 — Scan and propose:

help_init(action="scan")

This returns a list of proposed features with name, description, files, tags, confidence, and reason.

Present the proposals to the user as a table:

Feature	Confidence	Description	Files

Ask the user (Socratic):

• Which features to keep, rename, or remove?
• Are there features the scanner missed?
• Should any features be merged or split?

Step 2 — Accept and generate:

Once the user confirms, pass the accepted list:

help_init(
    action="accept",
    accepted=[
        {
            "name": "authentication",
            "description": "User auth and sessions",
            "files": ["src/auth/**"],
            "tags": ["security", "users"]
        },
        ...
    ]
)

This creates .help/features.yaml and generates concept, task, and reference templates for each feature. The response includes a preamble for each feature — display these so the user can verify the generated summaries are accurate. Tell the user: "Commit .help/ to your repo to share help with your team."

Status (/coach status)

Show which features have stale help templates:

help_status()

Or check specific features only:

help_status(features=["auth", "api"])

Present the report field as markdown. If stale features exist, ask: "Want me to regenerate the stale ones?"

Maintain (/coach maintain)

Full refresh — check all features and regenerate stale templates.

Preview what's stale (dry run):

help_update(dry_run=true)

Regenerate stale templates:

help_update()

Report the count of stale features found, which were regenerated, and any failures.

For plugin-internal help maintenance (attune-ai's own templates in plugin/help/generated/), use the separate help_maintain tool:

help_maintain(dry_run=false)

Update (/coach update <feature>)

Targeted regeneration for one feature:

help_update(features=["<feature>"])

Report which templates were regenerated and the result counts.

Add (/coach add <feature>)

Add a new feature to the manifest. Ask the user:

1. Feature name (slug, e.g. "authentication")
2. Description (one line)
3. File patterns (globs)
4. Tags (optional)

Then call help_init with the single new feature added to the accepted list from the existing manifest. Or use the Write tool to append the feature directly to .help/features.yaml, then call:

help_update(features=["<new-feature-name>"])

Output

Present the returned body as-is (it's already formatted markdown). Append the level indicator:

• Level 0: "(concept view — say 'tell me more' for step-by-step guide)"
• Level 1: "(procedural view — say 'tell me more' for full reference)"
• Level 2: "(reference view — full detail)"

If the result includes related entries, list them as suggested next reads.