Plan Format

Plans submitted via the CLI follow a hierarchical structure that maps to Kindship's planning system.

Hierarchy

PRIME_DIRECTIVE
└── OBJECTIVE
    └── PROJECT or PROCESS
        └── TASK (Actionable work item)

When you submit a plan, the CLI automatically ensures a PRIME_DIRECTIVE and OBJECTIVE exist for the agent, then creates your PROJECT/PROCESS with its tasks underneath.

JSON Format

Plans are submitted as JSON files:

{
  "title": "Build User Authentication",
  "description": "Implement secure user authentication system",
  "type": "PROJECT",
  "status": "DRAFT",
  "tags": ["auth", "security"],
  "skip_bootstrap": false,
  "tasks": [
    {
      "title": "Add Google OAuth",
      "description": "Configure and implement Google OAuth sign-in",
      "execution_mode": "HYBRID",
      "sequence_order": 1
    },
    {
      "title": "Add GitHub OAuth",
      "description": "Configure and implement GitHub OAuth sign-in",
      "execution_mode": "HYBRID",
      "sequence_order": 2,
      "dependencies_labeled": {
        "oauth_setup": "<uuid-of-previous-task>"
      }
    }
  ]
}

Process with Recurrence

For recurring processes, use type: "PROCESS" with a recurrence_pattern:

{
  "title": "Daily Health Check",
  "description": "Run daily system health checks",
  "type": "PROCESS",
  "status": "ACTIVE",
  "recurrence_pattern": "daily",
  "skip_bootstrap": true,
  "tasks": [
    {
      "title": "Check system status",
      "execution_mode": "BASH",
      "code": "kindship status --json"
    }
  ]
}

Submitting Plans

From File

kindship plan submit plan.json

From Stdin

cat plan.json | kindship plan submit

Plan Properties

Top-level properties for the plan:

Status Behavior

• DRAFT (default): Entity and tasks created as drafts. A bootstrap project is created to review and activate them.
• ACTIVE: Entity and tasks created as active, ready for execution. Bootstrap is skipped automatically.
• SUSPENDED: Entity created in suspended state.

If skip_bootstrap is true but no status is specified, entities are created as ACTIVE.

Recurrence Patterns

Valid patterns for recurrence_pattern (only on PROCESS type):

• hourly, daily, weekly, monthly
• continuous (runs immediately after completion)
• Cron expressions (e.g., 0 9 * * MON-FRI)

Task Properties

Each task in the tasks array can include:

Execution Modes

Dependencies

Tasks can depend on other tasks using dependencies_labeled:

{
  "tasks": [
    {
      "title": "Setup CI",
      "sequence_order": 1
    },
    {
      "title": "Write tests",
      "sequence_order": 2
    },
    {
      "title": "Deploy to staging",
      "sequence_order": 3,
      "dependencies_labeled": {
        "ci": "<uuid-of-setup-ci-task>",
        "tests": "<uuid-of-write-tests-task>"
      }
    }
  ]
}

The CLI ensures tasks execute in the correct order based on both sequence_order and dependencies.

Export Format

kindship plan export produces a flat JSON array of entities with UUID references. This format is round-trip safe — you can export and re-import without duplicating entities.

{
  "entities": [
    {
      "id": "aaa-...",
      "type": "PROJECT",
      "title": "My Project",
      "parent_id": null,
      "status": "ACTIVE",
      "description": "...",
      "execution_mode": "ORCHESTRATE",
      "sequence_order": 0,
      "tags": ["my-tag"]
    },
    {
      "id": "bbb-...",
      "type": "TASK",
      "title": "First Task",
      "parent_id": "aaa-...",
      "status": "ACTIVE",
      "execution_mode": "BASH",
      "sequence_order": 1,
      "code": "echo hello"
    }
  ],
  "_metadata": {
    "root_id": "aaa-...",
    "agent_id": "162c...",
    "total_entities": 2,
    "depth": 2,
    "exported_at": "2026-02-18T..."
  }
}

Key properties of the export format:

• parent_id: The root entity has parent_id: null. All other entities reference their parent's UUID.
• Topological order: Parents always appear before their children in the array.
• Empty fields omitted: Fields like description, code, tags are omitted when empty.
• _metadata: Summary info (not used during import).

Exporting

kindship plan export <entity-id>                     # Text tree view
kindship plan export <entity-id> --format json       # JSON output
kindship plan export <entity-id> --output plan.json  # Save to file
kindship plan export <entity-id> --include-deleted   # Include deleted entities

Importing

kindship plan import accepts the same flat JSON format produced by export. It performs an upsert: entities with existing UUIDs are updated, new UUIDs are created.

kindship plan import plan.json                        # From file
cat plan.json | kindship plan import                  # From stdin
kindship plan export <id> | kindship plan import      # Round-trip pipe

Import rules:

• The root entity (parent_id: null) must be PROJECT or PROCESS.
• The root is attached under the agent's OBJECTIVE (created automatically if missing).
• Exactly one root entity is required per import.
• All parent_id references must point to other entities in the same array.

Viewing Plans

After submission, view your plan:

kindship plan next            # Get the next executable task
kindship plan next --format text  # Human-readable output