Get file-level tracking status using MAID Runner.

When to use:

• Project health check: See which files lack manifests

• Onboarding: Identify files that need to be brought under MAID

• Compliance audit: Ensure all source files are tracked

Status categories:

• undeclared: Files not referenced in any manifest (needs attention)

• registered: Files in manifests but with potential issues

• tracked: Files fully compliant with MAID methodology

Tips:

• Use issues_only=True to focus on problem files

• Filter by status="undeclared" to find files needing manifests

• Run periodically to maintain MAID compliance

Args: manifest_dir: Directory containing manifests (default: "manifests") issues_only: If True, only show files with issues status: Filter by status (e.g., "undeclared", "registered", "tracked")

Returns: FileTrackingResult with categorized files

Generate test stubs from a manifest using MAID Runner.

When to use:

• Phase 2 (Planning): After creating manifest, generate test file skeleton

• Jumpstarting tests: Create boilerplate test structure from manifest

• Consistency: Ensure test file naming matches manifest conventions

What it generates:

• Test file with naming pattern: tests/test_task_XXX_*.py

• Test class structure based on expectedArtifacts

• Import statements for artifacts being tested

• Placeholder test methods for each artifact

Tips:

• Run after creating/updating a manifest

• Generated stubs are starting points - add assertions

• Test file is added to manifest's readonlyFiles automatically

Args: ctx: MCP context containing session and roots information manifest_path: Path to the manifest JSON file

Returns: GenerateStubsResult with generation outcome

Initialize a MAID project using MAID Runner.

When to use:

• Starting a new project: Set up MAID directory structure

• Onboarding existing project: Add MAID support to existing codebase

• Resetting: Use force=True to reinitialize

What it creates:

• manifests/ directory for task manifests

• .maid/ directory for MAID configuration

• Basic MAID project structure

Tips:

• Run once at project setup

• Use force=True only if you need to reset MAID configuration

Args: target_dir: Directory to initialize (defaults to current directory) force: Whether to force initialization even if already initialized

Returns: InitResult with initialization outcome

List manifests that reference a file using MAID Runner.

When to use:

• Before editing: Check if a file already has manifests

• Understanding history: See how a file has evolved through manifests

• Planning edits: Find related manifests to understand context

Result categories:

• created_by: Manifests where file is in creatableFiles

• edited_by: Manifests where file is in editableFiles

• read_by: Manifests where file is in readonlyFiles

Tips:

• Use before creating a new manifest for an existing file

• If file is in creatableFiles, it was first created by that manifest

• Use --use-manifest-chain in maid_validate for files with history

Args: file_path: Path to the file to check manifest_dir: Directory containing manifests (default: "manifests")

Returns: ListManifestsResult with manifest information

Get the MAID manifest JSON schema.

When to use:

• Phase 2 (Planning): Understand manifest structure before creating one

• Debugging: Verify manifest fields are correctly named and typed

• Learning: Explore available manifest options

Key information in schema:

• Required fields: goal, readonlyFiles, expectedArtifacts/systemArtifacts

• File lists: creatableFiles, editableFiles, readonlyFiles

• Artifact types: function, class, attribute, etc.

• Validation commands: validationCommand or validationCommands

Tips:

• Review schema before writing your first manifest

• Use schema to validate manifest structure

• Check artifact type options for expectedArtifacts.contains[]

Args: ctx: MCP context for accessing client roots

Returns: SchemaResult with the manifest schema

Generate a manifest snapshot from existing code using MAID Runner.

When to use:

• Onboarding existing code: Create manifests for pre-existing files

• Before refactoring: Capture current state as a baseline

• Documentation: Generate manifest to document existing APIs

Key behavior:

• Analyzes source file to extract public artifacts (functions, classes)

• Creates a manifest with expectedArtifacts matching current code

• Optionally generates test stub file for the manifest

Tips:

• Use before making changes to existing code without manifests

• The generated manifest serves as a "snapshot" of current state

• Review and adjust the generated manifest as needed

Args: file_path: Path to the source file to generate a snapshot for output_dir: Directory to output the manifest (default: "manifests") force: Whether to overwrite existing manifest files skip_test_stub: Whether to skip generating test stub file

Returns: SnapshotResult with generation outcome

Generate a system-wide manifest snapshot using MAID Runner.

When to use:

• Documentation: Create a comprehensive view of all project artifacts

• Architecture review: See all public APIs across the codebase

• Dependency analysis: Understand cross-file relationships

What it creates:

• Aggregated manifest combining all individual manifests

• System-wide view of all tracked artifacts

• Uses systemArtifacts (array) instead of expectedArtifacts (object)

Tips:

• Run periodically to update system documentation

• Useful for onboarding new team members

• Compare snapshots over time to track API evolution

Args: output: Path to the output system manifest file (default: "system.manifest.json") manifest_dir: Directory containing individual manifests (default: "manifests") quiet: Whether to suppress progress output (default: True)

Returns: SystemSnapshotResult with generation outcome

Validate a MAID manifest using MAID Runner.

When to use:

• Phase 2 (Planning): After creating/updating a manifest, validate it passes

• Phase 3 (Implementation): After writing code, verify it matches the manifest

• Before committing: Ensure all manifests are valid

Validation modes:

• implementation: Checks that code artifacts match manifest expectedArtifacts

• behavioral: Checks that tests exist and reference the expected artifacts

• schema: Checks that the manifest structure conforms to the JSON schema

Use manifest chain when:

• Editing existing files (taskType: "edit")

• The file has previous manifests that define its history

• You need to verify the full history of changes is valid

Args: manifest_path: Path to the manifest JSON file validation_mode: Validation mode (implementation, behavioral, or schema) use_manifest_chain: Whether to use manifest chain for validation manifest_dir: Directory containing manifests (optional) quiet: Whether to suppress verbose output ctx: MCP context for accessing working directory

Returns: ValidateResult with validation outcome