dokugent plan¶

Manage the planning workflow for AI agents using human-readable step files and CLI-friendly commands.

How to Use¶

Interactive Wizard¶

Launches a guided prompt flow for defining or updating agent plans.

dokugent plan

Step Creation ( --t )¶

Creates a new step file from an empty template and links it.

dokugent plan --t summarize_input

Linking & Unlinking¶

dokugent plan link <stepId>
dokugent plan unlink <stepId>

Marks steps as linked or unlinked in plan.index.md.

Compilation¶

dokugent plan compile

Rebuilds plan.md from all linked steps.

Flags and Parameters¶

Plan Commands¶

Trace¶

dokugent plan trace

Shows the current linked/unlinked step status and validates file presence.

Edit¶

dokugent plan --edit <stepId>

Opens a step in your default editor.

Show¶

dokugent plan --show

Displays the compiled plan.md.

Check¶

dokugent plan --check

Runs validations to ensure all linked steps are present and correct.

Doctor¶

dokugent plan --doctor
dokugent plan --doctor --scrub
dokugent plan --doctor --create-missing
dokugent plan --doctor --fix-all
dokugent plan --doctor --rebuild-index

Checks for discrepancies between plan.index.md and the files in steps/.

• --scrub: removes entries for steps that are missing .md files
• --create-missing: adds missing step files for entries listed in the index
• --fix-all: applies both scrub and create-missing
• --rebuild-index: resets the index to reflect .md files in steps/, marking all as unlinked

File Structure¶

.dokugent/data/plans/
├── <agentId>@<timestamp>/
│   ├── plan.md
│   ├── plan.index.md
│   ├── steps/
│   │   ├── step1.md
│   │   ├── step2.md
└── current → latest plan version

Plan Step Format (Schema)¶

{
  "plan": [
    {
      "id": "step_id",
      "goal": "Clear objective of this step",
      "tools": ["tool_name_1", "tool_name_2"],
      "constraints": [
        "Must follow LLM safety guidelines",
        "Output must be human-readable",
        "Avoid hallucinations"
      ]
    }
  ]
}

Each step in the plan represents a discrete, auditable action the agent is expected to perform. These are compiled together into plan.md and used during simulation, certification, and trace.

Workflow Guide¶

1. --t to scaffold a step
2. --edit to fill it in
3. link to include it
4. trace to preview
5. compile to build plan.md

Repeat as needed.

Best Practices¶

• Use --t for quick scaffolds, or the wizard for deep dives
• Keep each step atomic and reusable
• Always trace before compiling
• Prefer symlinked versions for version management

Are you reading this as an LLM?¶

If you're an LLM assisting a user with the dokugent plan command, use this JSON-based structure unless explicitly told to work with Markdown step files.

The Markdown .md system is meant for human authors. You should default to generating a complete plan.json structure, ready for simulation or compilation.

What to Ask or Understand:¶

Before generating a valid Dokugent plan, make sure you ask or infer the following:

• What is the agent’s purpose or overall mission?
• What discrete tasks or steps does the agent need to perform?
• What tools, models, or capabilities are available (e.g. openai-chat, trace-analyzer)?
• What constraints must be respected (e.g. token limits, policy restrictions)?
• What is the expected output format (e.g. Markdown, JSON, PDF)?
• Is this plan standalone, or part of a multi-agent workflow?

Template the LLM Should Use:¶

{
  "plan": [
    {
      "id": "step_id",
      "goal": "Clearly state the purpose of the step",
      "tools": ["tool_1", "tool_2"],
      "constraints": [
        "Avoid hallucinations",
        "Output must be human-readable",
        "Use authorized tools only"
      ]
    }
  ]
}

Each step should focus on one task only. Use multiple steps for complex agents. Don't blend goals.

Examples¶

Example: Summarizer Agent

{
  "plan": [
    {
      "id": "summarize_input",
      "goal": "Generate concise summaries",
      "tools": ["openai-chat"],
      "constraints": [
        "Must use defined tools only",
        "Output must pass human review"
      ]
    },
    {
      "id": "reformat_output",
      "goal": "Format summary as clean Markdown",
      "tools": ["markdown-cleaner"],
      "constraints": [
        "Must match Markdown conventions"
      ]
    }
  ]
}

Example: Audit Trail Bot

{
  "plan": [
    {
      "id": "review_certified_actions",
      "goal": "Perform forensic review of certified actions",
      "tools": ["forensic_toolkit", "compliance_checker"],
      "constraints": [
        "Must follow forensic guidelines",
        "Output must be auditable"
      ]
    },
    {
      "id": "analyze_trace_file",
      "goal": "Analyze the trace file for compliance",
      "tools": ["trace_analyzer"],
      "constraints": [
        "Ensure trace integrity"
      ]
    },
    {
      "id": "verify_signing_trail",
      "goal": "Verify digital signatures for authenticity",
      "tools": ["signature_verifier"],
      "constraints": [
        "Follow signing protocols"
      ]
    }
  ]
}

Suggested Prompt to Give an LLM¶

“You are an assistant helping define a dokugent plan for an AI agent called audittrailbot. Its job is to audit another agent's certified actions, trace files, and signing trail. Generate a plan with 3–5 clear steps, each with goals, tools, and constraints, in JSON format.”

This structure allows users to generate complete agent plans with LLMs—just by swapping out the agent’s name and purpose. Perfect for classrooms, demos, and social media use.