ailey-admin-manage-plan

id	null
name	ailey-admin-manage-plan
description	Manage .project/PLAN.json with schema evolution, CRUD operations, and jq-style queries. Use when creating, reading, updating, or deleting plan items, validating against schemas, migrating between schema versions, or querying plan data with complex filters. Supports ID and name-based searches.

AI-ley Manage Plan

Comprehensive management tool for .project/PLAN.json with schema evolution, CRUD operations, and jq-style querying capabilities.

Overview

The manage-plan skill provides complete lifecycle management for PLAN.json:

Schema Management:

• Initialize empty PLAN.json from schema
• Validate against versioned schemas (.github/aicc/schemas/plan.v*.schema.json)
• Check schema evolution and compatibility
• Migrate data between schema versions
• Support forward/backward/full compatibility modes

Data Operations:

• CRUD: Create, Read, Update, Delete plan items
• Search: Find items by ID or name
• Query: jq-style queries for complex filtering
• Bulk: Update or delete multiple items with queries

Integration:

• Leverages ailey-tools-data-converter modules for shared functionality
• Schema validation with AJV
• Compatible with existing PLAN.json structure

When to Use

Use this skill when:

• Initializing: Creating new PLAN.json from scratch
• Querying: Finding specific items by ID, name, or complex criteria
• Updating: Modifying plan items, status, or metadata
• Bulk Operations: Updating multiple items at once
• Schema Evolution: Migrating to new schema versions
• Validation: Ensuring PLAN.json conforms to schema
• Statistics: Generating reports on plan status and progress

Initialize PLAN.json

Create empty PLAN.json from schema:

tsx scripts/manage-plan.ts create --init --schema v1

Find Items

Search by ID:

tsx scripts/manage-plan.ts read --id AICC-001

Search by name (partial match):

tsx scripts/manage-plan.ts read --name "authentication"

Query with jq-style

Find all backlog items:

tsx scripts/manage-plan.ts query '.items[] | select(.status == "BACKLOG")'

Find high-priority items:

tsx scripts/manage-plan.ts read --query '.items[] | select(.priority == "high")'

Update Items

Update by ID:

tsx scripts/manage-plan.ts update --id AICC-001 --value '{"status":"IN-PROGRESS"}'

Bulk update with query:

tsx scripts/manage-plan.ts update \
  --query '.items[] | select(.status == "READY")' \
  --set '.status = "IN-PROGRESS"'

Delete Items

Delete by ID:

tsx scripts/manage-plan.ts delete --id AICC-999

Delete by query:

tsx scripts/manage-plan.ts delete --query '.items[] | select(.status == "SKIP")'

Workflow 1: Initialize and Populate Plan

Create new PLAN.json and add items:

1. Initialize from schema:

   tsx scripts/manage-plan.ts create --init --schema v1
   

2. Add first item:

   tsx scripts/manage-plan.ts create \
     --path '.items' \
     --value '{"id":"PROJ-001","type":"epic","summary":"Project Setup","status":"BACKLOG","priority":"high"}'
   

3. Validate:

   tsx scripts/manage-plan.ts schema validate
   

Workflow 2: Query and Update

Find and update specific items:

1. Find ready items:

   tsx scripts/manage-plan.ts query '.items[] | select(.status == "READY")' --output table
   

2. Move to in-progress:

   tsx scripts/manage-plan.ts update \
     --query '.items[] | select(.status == "READY")' \
     --set '.status = "IN-PROGRESS"'
   

3. Verify changes:

   tsx scripts/manage-plan.ts stats
   

Workflow 3: Schema Evolution

Migrate to new schema version:

1. Check compatibility:

   tsx scripts/manage-plan.ts schema evolve \
     --from v1 \
     --to v2 \
     --check backward \
     --report
   

2. Migrate data:

   tsx scripts/manage-plan.ts schema migrate \
     --from v1 \
     --to v2 \
     --backup
   

3. Validate:

   tsx scripts/manage-plan.ts schema validate --schema v2
   

Workflow 4: Bulk Updates

Update multiple items efficiently:

1. Find items to update:

   tsx scripts/manage-plan.ts read --query '.items[] | select(.assignee == null)'
   

2. Bulk assign:

   tsx scripts/manage-plan.ts update \
     --query '.items[] | select(.assignee == null)' \
     --set '.assignee = "[e-mail]"'
   

3. Verify:

   tsx scripts/manage-plan.ts stats
   

Create

# Initialize empty PLAN.json
tsx scripts/manage-plan.ts create --init [--schema v1]

# Create item at path
tsx scripts/manage-plan.ts create \
  --path <jq-path> \
  --value <json>

Options:

• --file <path> - PLAN.json location (default: .project/PLAN.json)
• --schema <version> - Schema version for init (default: v1)
• --path <jq-path> - Path to create item
• --value <json> - JSON value
• --init - Initialize empty file

Read

# Read all
tsx scripts/manage-plan.ts read

# Read by ID
tsx scripts/manage-plan.ts read --id <item-id>

# Read by name
tsx scripts/manage-plan.ts read --name <partial-name>

# Read with query
tsx scripts/manage-plan.ts read --query <jq-expression>

# Read at path
tsx scripts/manage-plan.ts read --path <jq-path>

Options:

• --file <path> - PLAN.json location
• --id <id> - Search by ID
• --name <name> - Search by name (partial match)
• --query <jq> - jq-style query
• --path <jq-path> - Path to read
• --output <format> - Output format: json, yaml, table (default: json)

Update

# Update by ID
tsx scripts/manage-plan.ts update \
  --id <item-id> \
  --value <json>

# Update by query
tsx scripts/manage-plan.ts update \
  --query <jq-expression> \
  --set <jq-set-expression>

# Update at path
tsx scripts/manage-plan.ts update \
  --path <jq-path> \
  --value <json>

Options:

• --file <path> - PLAN.json location
• --id <id> - Update by ID
• --query <jq> - Query to select items
• --set <jq> - Set expression (e.g., .status = "DONE")
• --path <jq-path> - Path to update
• --value <json> - New value
• --validate - Validate after update (default: true)

Delete

# Delete by ID
tsx scripts/manage-plan.ts delete --id <item-id>

# Delete by query
tsx scripts/manage-plan.ts delete --query <jq-expression>

# Delete at path
tsx scripts/manage-plan.ts delete --path <jq-path>

Options:

• --file <path> - PLAN.json location
• --id <id> - Delete by ID
• --query <jq> - Query to select items
• --path <jq-path> - Path to delete
• --validate - Validate after deletion (default: true)

Query

# Query with jq expression
tsx scripts/manage-plan.ts query <expression> [options]

Options:

• --file <path> - PLAN.json location
• --output <format> - Output format: json, yaml, table
• --compact - Compact JSON output

Query Examples:

# All backlog items
'.items[] | select(.status == "BACKLOG")'

# High-priority items
'.items[] | select(.priority == "high")'

# Items by type
'.items[] | select(.type == "epic")'

# Multiple conditions
'.items[] | select(.status == "BACKLOG" and .priority == "high")'

# Just IDs
'.items[] | .id'

# Count by status
'.items | group_by(.status) | map({status: .[0].status, count: length})'

Schema Management

# Validate
tsx scripts/manage-plan.ts schema validate [--schema v1]

# Check evolution
tsx scripts/manage-plan.ts schema evolve \
  --from v1 \
  --to v2 \
  --check <mode> \
  [--report]

# Migrate
tsx scripts/manage-plan.ts schema migrate \
  --from v1 \
  --to v2 \
  [--output <path>] \
  [--backup]

Compatibility Modes:

• forward - Old code can read new data
• backward - New code can read old data
• full - Both forward and backward
• none - No compatibility required

Statistics

# Show plan statistics
tsx scripts/manage-plan.ts stats

Output:

• Version
• Total items
• Status counts (BACKLOG, READY, IN-PROGRESS, etc.)
• Last updated
• Schema version

jq Query Syntax

Supported jq-style operations:

Selectors

• .field - Access field
• .field.nested - Nested access
• .items[] - Iterate array
• .items[0] - Array index

Filters

• select(.field == "value") - Filter items
• select(.field != "value") - Not equal
• select(.field > 10) - Greater than
• select(.field < 10) - Less than

Operators

• == - Equal
• != - Not equal
• > - Greater than
• < - Less than
• >= - Greater or equal
• <= - Less or equal

Examples

# Status filter
'.items[] | select(.status == "BACKLOG")'

# Priority filter
'.items[] | select(.priority == "high")'

# Type filter
'.items[] | select(.type == "epic")'

# Multiple conditions (AND)
'.items[] | select(.status == "READY" and .priority == "high")'

# Field extraction
'.items[] | .id'
'.items[] | .summary'

Compatibility Rules

Forward Compatible:

• ✅ Add optional fields
• ✅ Relax restrictions
• ❌ Remove fields
• ❌ Add required fields

Backward Compatible:

• ✅ Add optional fields with defaults
• ❌ Remove required fields
• ❌ Tighten restrictions

Full Compatible:

• Intersection of forward and backward rules

Migration Process

1. Check Compatibility:

   tsx scripts/manage-plan.ts schema evolve --from v1 --to v2 --check backward --report
   

2. Review Report: Check for breaking changes

3. Backup: Create backup before migration

4. Migrate:

   tsx scripts/manage-plan.ts schema migrate --from v1 --to v2 --backup
   

5. Validate:

   tsx scripts/manage-plan.ts schema validate --schema v2
   

Integration with Data Converter

This skill leverages shared modules from ailey-tools-data-converter:

// Shared schema validation
import { SchemaValidator } from '../ailey-tools-data-converter/lib/schema';

// Shared query engine
import { QueryExecutor } from '../ailey-tools-data-converter/lib/query';

// Shared CRUD operations
import { CRUDOperations } from '../ailey-tools-data-converter/lib/crud';

Benefits:

• Consistent schema validation across skills
• Shared jq query engine
• Reusable CRUD patterns
• Reduced code duplication

Performance

Optimizations:

• In-memory data loading for fast operations
• Efficient ID-based lookups
• Lazy schema loading
• Atomic file writes with backups

Typical Performance:

• Read: <10ms
• Update single item: <50ms
• Query (1000 items): <100ms
• Validation: <200ms

Error Handling

The tool provides clear error messages:

❌ PLAN.json not found at .project/PLAN.json. Use 'create --init' to initialize.
❌ Item not found: AICC-999
❌ Schema not found: .github/aicc/schemas/plan.v3.schema.json
❌ PLAN.json validation failed
❌ Schemas are NOT backward compatible

Resources

• Script: scripts/manage-plan.ts - Main CLI tool
• Library: lib/plan-manager.ts - Core functionality
• Schemas: .github/aicc/schemas/plan.v*.schema.json - JSON Schema definitions
• Data: .project/PLAN.json - Plan data file

Related Skills

• ailey-tools-data-converter: Shared modules for schema, query, CRUD operations
• ailey-admin-tools-index: Index management for skill discovery
• ailey-progress-report: Generate progress reports from PLAN.json

---

Version: 1.0.0
Created: 2026-01-29
Score: 4.5

---

version: 1.0.0 updated: 2026-01-30 reviewed: 2026-01-30 score: 4.2