GoDD MCP α Documentation

Go from first-time setup to everyday development, quality checks, and delivery. Choose a goal and start with copy-ready examples.

Get started

Prepare the requirements, then run these four inputs in order.

A license key is required

GoDD MCP α requires a valid GoDD license key. One product license enables normal features; you do not issue a separate audit key.

  1. Review plans and create an account
  2. Choose a subscription
  3. Issue your license key from the dashboard

Start in three steps

Use Node.js 22+ with Cursor, Claude Code, Codex, Kimi CLI, or Antigravity.

npm install -g @autodevjapan/godd-mcp-alpha
godd-a install --license-key=YOUR_LICENSE_KEY
godd-a init
/godd-a/dev Add profile editing

Choose a goal

Pick a common workflow to see which commands to use next.

Build and publish a feature

Clarify requirements, implement, verify quality, and hand the change to review.

  1. 1/godd-a/dev
  2. 2/godd-a/check
  3. 3/godd-a/ship

Fix a defect safely

Trace impact, add a reproduction test, and verify that regressions are prevented.

  1. 1/godd-a/impact
  2. 2/godd-a/test
  3. 3/godd-a/check

Explain and share a change

Update user docs, review the result, and create a pull request.

  1. 1/godd-a/docs
  2. 2/godd-a/review
  3. 3/godd-a/pr

Complete feature reference

Open a command to see when to use it, prerequisites, an example, expected results, and recovery steps.

Development and quality

/godd-a/dev/godd-a-devGuides requirements, implementation, tests, quality checks, and documentation in stages.
What it does
Guides requirements, implementation, tests, quality checks, and documentation in stages.
When to use it
Use it for a feature or bug fix that needs a plan and verification.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
The change scope, implementation, and verification results are presented.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “The change scope, implementation, and verification results are presented.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/dev Add retry behavior for failed sign-ins
/godd-a/check/godd-a-checkChecks specification alignment, tests, types, lint, and security.
What it does
Checks specification alignment, tests, types, lint, and security.
When to use it
Use it before committing or handing work to review.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the changed files and the verification commands available in the project.
Expected result
Each check and its PASS, FAIL, or INCONCLUSIVE evidence is reported.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the changed files and the verification commands available in the project. If the result does not match “Each check and its PASS, FAIL, or INCONCLUSIVE evidence is reported.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/check
/godd-a/ship/godd-a-shipMoves verified work through quality checks, commit, push, and pull request.
What it does
Moves verified work through quality checks, commit, push, and pull request.
When to use it
Use it when a finished change is ready for review.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the Git remote, GitHub sign-in, and permission for the target branch.
Expected result
A reviewed branch and pull request are produced after required gates pass.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the Git remote, GitHub sign-in, and permission for the target branch. If the result does not match “A reviewed branch and pull request are produced after required gates pass.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/ship

What to use next

/godd-a/review/godd-a-reviewReviews changes for quality, design, security, and operations.
What it does
Reviews changes for quality, design, security, and operations.
When to use it
Use it before a pull request or when an independent perspective is needed.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the changed files and the verification commands available in the project.
Expected result
Findings are prioritized with evidence and proposed fixes.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the changed files and the verification commands available in the project. If the result does not match “Findings are prioritized with evidence and proposed fixes.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/review
/godd-a/test/godd-a-testCreates or runs the tests required by a change.
What it does
Creates or runs the tests required by a change.
When to use it
Use it to reproduce a defect, prove acceptance criteria, or prevent regression.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the changed files and the verification commands available in the project.
Expected result
Commands, exit status, and failure causes are reported.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the changed files and the verification commands available in the project. If the result does not match “Commands, exit status, and failure causes are reported.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/test Add a regression test for sign-in retries

What to use next

GitHub and releases

/godd-a/commit/godd-a-commitCommits verified changes at an intentional granularity.
What it does
Commits verified changes at an intentional granularity.
When to use it
Use it when one change objective and its test evidence are complete.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the changed files and the verification commands available in the project.
Expected result
Only the intended diff is committed with a clear message.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the changed files and the verification commands available in the project. If the result does not match “Only the intended diff is committed with a clear message.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/commit

What to use next

/godd-a/push/godd-a-pushPushes the current branch to its configured remote.
What it does
Pushes the current branch to its configured remote.
When to use it
Use it to share commits or prepare a pull request.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the Git remote, GitHub sign-in, and permission for the target branch.
Expected result
The destination branch and push result are reported.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the Git remote, GitHub sign-in, and permission for the target branch. If the result does not match “The destination branch and push result are reported.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/push

What to use next

/godd-a/pr/godd-a-prCreates a pull request that follows the repository template.
What it does
Creates a pull request that follows the repository template.
When to use it
Use it when the branch is ready for review.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the Git remote, GitHub sign-in, and permission for the target branch.
Expected result
A pull request is created with summary, tests, and linked issue.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the Git remote, GitHub sign-in, and permission for the target branch. If the result does not match “A pull request is created with summary, tests, and linked issue.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/pr
/godd-a/deploy/godd-a-deployDeploys with verification and a rollback plan.
What it does
Deploys with verification and a rollback plan.
When to use it
Use it to promote approved changes to staging or production.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target environment, deployment permission, approval, and recovery steps.
Expected result
The target, verification, and recovery steps are reported.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target environment, deployment permission, approval, and recovery steps. If the result does not match “The target, verification, and recovery steps are reported.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/deploy production

What to use next

/godd-a/release/godd-a-releaseBuilds SemVer-aligned release notes from the change history.
What it does
Builds SemVer-aligned release notes from the change history.
When to use it
Use it when announcing a new version to users.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the Git remote, GitHub sign-in, and permission for the target branch.
Expected result
User-facing changes, cautions, and upgrade steps are organized.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the Git remote, GitHub sign-in, and permission for the target branch. If the result does not match “User-facing changes, cautions, and upgrade steps are organized.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/release 1.4.0

What to use next

/godd-a/github/godd-a-githubHelps inspect and configure repository and branch-protection settings.
What it does
Helps inspect and configure repository and branch-protection settings.
When to use it
Use it when preparing a repository or establishing review rules.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the Git remote, GitHub sign-in, and permission for the target branch.
Expected result
Required setting changes and their result are reported.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the Git remote, GitHub sign-in, and permission for the target branch. If the result does not match “Required setting changes and their result are reported.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/github Configure branch protection for main

What to use next

Documentation and design

/godd-a/docs/godd-a-docsCreates or updates user documentation to match a code change.
What it does
Creates or updates user documentation to match a code change.
When to use it
Use it when setup, operation, configuration, or visible behavior changes.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the audience, documents to update, and output location.
Expected result
The relevant guide is updated and checked against the implementation.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the audience, documents to update, and output location. If the result does not match “The relevant guide is updated and checked against the implementation.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/docs Update setup steps for the current CLI

What to use next

/godd-a/adr/godd-a-adrRecords an important technical decision as an Architecture Decision Record.
What it does
Records an important technical decision as an Architecture Decision Record.
When to use it
Use it when choosing a long-lived approach from multiple options.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the decision, constraints, and alternatives to compare.
Expected result
An ADR captures context, options, decision, and consequences.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the decision, constraints, and alternatives to compare. If the result does not match “An ADR captures context, options, decision, and consequences.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/adr Use PostgreSQL for audit logs
/godd-a/map/godd-a-mapCreates a Mermaid knowledge graph of architecture and dependencies.
What it does
Creates a Mermaid knowledge graph of architecture and dependencies.
When to use it
Use it to understand an unfamiliar codebase or prepare a broad change.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
A diagram of key components and dependency directions is updated.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “A diagram of key components and dependency directions is updated.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/map
/godd-a/diagram/godd-a-diagramUpdates Mermaid architecture diagrams to match the code.
What it does
Updates Mermaid architecture diagrams to match the code.
When to use it
Use it when dependencies, states, or component interactions change.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the audience, documents to update, and output location.
Expected result
The synchronized diagram and its changes are presented.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the audience, documents to update, and output location. If the result does not match “The synchronized diagram and its changes are presented.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/diagram

What to use next

/godd-a/slide/godd-a-slideCreates Marp presentation slides from project documents.
What it does
Creates Marp presentation slides from project documents.
When to use it
Use it to review or explain a design or project update.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the audience, documents to update, and output location.
Expected result
Presentation-ready slide content and open checks are produced.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the audience, documents to update, and output location. If the result does not match “Presentation-ready slide content and open checks are produced.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/slide docs/product-overview.md

What to use next

/godd-a/design/godd-a-designCreates or updates screen designs from the codebase.
What it does
Creates or updates screen designs from the codebase.
When to use it
Use it to align on UI before implementation or synchronize an existing screen.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm a runnable test environment, test account, and expected screen flow.
Expected result
The target design and implementation notes are presented.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm a runnable test environment, test account, and expected screen flow. If the result does not match “The target design and implementation notes are presented.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/design dashboard

What to use next

/godd-a/retro/godd-a-retroWrites the implementation history of a period as a retro report.
What it does
Writes the implementation history of a period as a retro report.
When to use it
Use it to close a sprint or hand work over with the period listed out.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the period to look back on and, if needed, the git author to filter by.
Expected result
The implementation history for that period is written to a gitignored Markdown file under .godd/retro/.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the period to look back on and, if needed, the git author to filter by. If the result does not match “The implementation history for that period is written to a gitignored Markdown file under .godd/retro/.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/retro since:1w

Project and operations

/godd-a/runRuns a GoDD command supplied as text.
What it does
Runs a GoDD command supplied as text.
When to use it
Use it when your client cannot invoke native slash commands.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
The requested public command is selected and its workflow starts.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “The requested public command is selected and its workflow starts.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/run /godd-a/check

What to use next

/godd-a/setup/godd-a-setupInspects the technology stack and guides reproducible environment setup.
What it does
Inspects the technology stack and guides reproducible environment setup.
When to use it
Use it when joining a repository or starting with a recommended stack.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
Missing information is identified and setup instructions are produced.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “Missing information is identified and setup instructions are produced.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/setup Prepare a TypeScript and React project
/godd-a/impact/godd-a-impactTraces references and the likely blast radius of a proposed change.
What it does
Traces references and the likely blast radius of a proposed change.
When to use it
Use it before changing shared functions, types, or configuration.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
Affected callers, tests, docs, and open questions are listed.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “Affected callers, tests, docs, and open questions are listed.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/impact src/auth/session.ts

What to use next

/godd-a/config/godd-a-configDetects the stack and generates or repairs config.godd.
What it does
Detects the stack and generates or repairs config.godd.
When to use it
Use it after initialization when project configuration is missing or invalid.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
Validated project settings and remaining questions are presented.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “Validated project settings and remaining questions are presented.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/config

What to use next

/godd-a/questions/godd-a-questionsResolves a list of open questions interactively.
What it does
Resolves a list of open questions interactively.
When to use it
Use it before implementation to settle requirements and choices.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
Answered and still-open questions are clearly separated.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “Answered and still-open questions are clearly separated.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/questions

What to use next

/godd-a/e2e/godd-a-e2eExercises critical user journeys in a browser.
What it does
Exercises critical user journeys in a browser.
When to use it
Use it for navigation and flows that cross multiple screens.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm a runnable test environment, test account, and expected screen flow.
Expected result
Steps, deviations from expected behavior, and reproduction evidence are shown.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm a runnable test environment, test account, and expected screen flow. If the result does not match “Steps, deviations from expected behavior, and reproduction evidence are shown.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/e2e Verify the checkout completion flow
/godd-a/learn/godd-a-learnSaves and recalls project-specific conventions, patterns, and pitfalls.
What it does
Saves and recalls project-specific conventions, patterns, and pitfalls.
When to use it
Use it to preserve a recurring decision or avoidance rule.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
A concise, reusable learning entry is stored.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “A concise, reusable learning entry is stored.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/learn Save the API naming convention
/godd-a/scratchpad/godd-a-scratchpadSaves, searches, and recalls working notes across conversations.
What it does
Saves, searches, and recalls working notes across conversations.
When to use it
Use it for temporary context needed in a later session.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the target files, requested change, and completion criteria.
Expected result
The save result or matching notes are returned.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the target files, requested change, and completion criteria. If the result does not match “The save result or matching notes are returned.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/scratchpad save "Checkout verified in staging"

What to use next

/godd-a/metrics/godd-a-metricsReports token efficiency and available evidence-based delivery metrics.
What it does
Reports token efficiency and available evidence-based delivery metrics.
When to use it
Use it when making an operational improvement decision from measured evidence.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the comparison target, measurement conditions, and available test results.
Expected result
Only verifiable metrics are shown with their sample information.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the comparison target, measurement conditions, and available test results. If the result does not match “Only verifiable metrics are shown with their sample information.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/metrics
/godd-a/plan/godd-a-planRuns an approved plan in resumable, ordered task units.
What it does
Runs an approved plan in resumable, ordered task units.
When to use it
Use it for multi-task work that needs durable state and deadlines.
Prerequisites
Install GoDD MCP α and complete godd-a init in the target repository before running this command. Confirm the decision, constraints, and alternatives to compare.
Expected result
The single next task and current plan state are returned.
If it does not work
If the command is not recognized, run godd-a version, restart the MCP client, and try again. Confirm the decision, constraints, and alternatives to compare. If the result does not match “The single next task and current plan state are returned.”, state the target and permissions explicitly, then retry.

Copy-ready example

/godd-a/plan start docs/approved-plan.md

What to use next

Client use and management

Send everyday requests in chat; use the terminal for installation and update checks.

Request work from chat

Usually, add your request after /godd-a/<feature>. Use run when direct invocation is unavailable.

/godd-a/dev Add profile editing
/godd-a/run /godd-a/check

Public CLI reference

godd-a install [--license-key=KEY] [--client=<id|all>]Detects supported clients and registers GoDD MCP α.
What it does
Detects supported clients and registers GoDD MCP α.
When to use it
Use it for first installation, a new client, or connection repair.
Prerequisites
Prepare Node.js 22+, a license key, and a supported client.
Expected result
The detected clients and registration results are shown.
If it does not work
If no client is detected, launch the client once to create its settings directory, then rerun with a client name from the supported list.

Copy-ready example

godd-a install --license-key=YOUR_LICENSE_KEY
godd-a init [--force] [--lang=LANG] [--auto]Generates config.godd and required guidance files for a project.
What it does
Generates config.godd and required guidance files for a project.
When to use it
Use it when adopting GoDD in a repository or regenerating settings.
Prerequisites
Complete godd-a install and run it from the repository root.
Expected result
Detected technologies and generated or updated files are listed.
If it does not work
If files are generated in the wrong place, move to the repository root, verify the documentation-directory setting in config.godd, and rerun.

Copy-ready example

godd-a init --lang=en
godd-a uninstall [--client=<id|all>]Removes GoDD registration and managed commands from selected clients.
What it does
Removes GoDD registration and managed commands from selected clients.
When to use it
Use it when retiring a client or resetting its registration.
Prerequisites
Confirm the client ID that should be removed.
Expected result
Only GoDD-managed configuration removal results are shown.
If it does not work
If the target is not found, verify the client ID. If removed entries remain visible, restart the client so it reloads its settings.

Copy-ready example

godd-a uninstall --client=cursor
godd-a serveStarts the MCP stdio server.
What it does
Starts the MCP stdio server.
When to use it
The client normally starts it automatically; run it manually only for diagnosis.
Prerequisites
Register the client with godd-a install.
Expected result
The server waits for client messages over standard input and output.
If it does not work
If the server exits immediately after connection, check the client launch command and environment variables, then run the same command in a terminal and inspect stderr.

Copy-ready example

godd-a serve
godd-a compatibilityPrints client-specific compression compatibility.
What it does
Prints client-specific compression compatibility.
When to use it
Use it when selecting a client or enabling compression.
Prerequisites
Install GoDD MCP α.
Expected result
A matrix shows OS, shell, usage, and what to do when unavailable.
If it does not work
If your client is absent from the table, leave compression disabled and confirm that the displayed OS and shell match the environment in use.

Copy-ready example

godd-a compatibility
godd-a codec-capability verify --npm-version <version> --manifest <path> --artifact <path> --runner <path>Verifies a distributed codec manifest, artifact, runner, and known answers.
What it does
Verifies a distributed codec manifest, artifact, runner, and known answers.
When to use it
Use it as a release operator validating distribution integrity.
Prerequisites
Prepare all four files and the npm version.
Expected result
A successful result or a safe failure reason is returned.
If it does not work
If verification fails, collect the manifest, artifact, runner, and known answers from the same distribution and retry with no missing or modified files.

Copy-ready example

godd-a codec-capability verify --npm-version 2.0.1 --manifest manifest.json --artifact codec.bin --runner codec-runner
godd-a impact evidence cobol --root <path> [--source-format fixed|free|variable]Extracts COBOL COPY, CALL, and EXEC relationships within safe limits.
What it does
Extracts COBOL COPY, CALL, and EXEC relationships within safe limits.
When to use it
Use it to add deterministic evidence to COBOL impact analysis.
Prerequisites
Identify a repository-local COBOL root and optional source format.
Expected result
JSON separates confirmed edges from unresolved and inconclusive signals.
If it does not work
If the root or a copybook cannot be read, use a repository-relative path and verify the source format. Treat unresolved CALL or COPY entries as follow-up work.

Copy-ready example

godd-a impact evidence cobol --root src/cobol --source-format fixed
godd-a dataset coverage --ledger <path>Validates sample results from standard input and saves progress to a file.
What it does
Validates sample results from standard input and saves progress to a file.
When to use it
Use it to track completed and missing dataset processing.
Prerequisites
Create the parent directory and save the JSON shown below to a file.
Expected result
Only validated samples are recorded and a JSON result is returned.
If it does not work
If input is rejected, copy the generation and digests from the previous result into the next JSON, and check for an unissued sample or expired attempt.

Copy-ready example

godd-a dataset coverage --ledger .godd/dataset-coverage.json

Input JSON (save as a file)

{
  "action": "initialize",
  "generation": { "source_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "split": "eval", "epoch": 1 },
  "assigned_sample_ids": ["private-video"],
  "expected_sample_ids": ["private-video"],
  "retry_policy": {
    "max_attempts": { "DecodeError": 1, "AnnotationMissing": 1, "FrameExtraction": 1, "SourceUnavailable": 1, "ResourceExhausted": 1, "AttemptTimeout": 1 },
    "backoff": { "max_backoff_ms": 0 },
    "attempt_timeout_ms": 600000,
    "run_wall_time_budget_ms": 3600000,
    "infrastructure_failure_storm_threshold": 2
  },
  "thresholds": { "min_coverage_ratio": 1.0, "max_class_failure_ratio": 0.1, "max_split_accepted_ratio_variance": 0.0, "max_replacement_ratio": 0.0 },
  "declared_threshold_digest": "343eb2b12236e6984358603780f16fd03c23a07ccd199f04d6a404ebbd350142",
  "declared_expected_sample_id_digest": "1b442df4911573935107a07e6cda5dafccc5832c09d7a8d38b6475be6ef47fc3",
  "replacement_policy": "forbidden"
}

PowerShell

Get-Content -Raw dataset-action.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

cat dataset-action.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

How to use each action

initialize

What it does
Use initialize to produce this result: tracking starts with one expected sample.
Prerequisites
Required: the JSON shown here and an existing .godd directory.
Expected result
Result: tracking starts with one expected sample.
If it does not work
If it fails: copy every field exactly and use an unused output file.
{
  "action": "initialize",
  "generation": { "source_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "split": "eval", "epoch": 1 },
  "assigned_sample_ids": ["private-video"],
  "expected_sample_ids": ["private-video"],
  "retry_policy": {
    "max_attempts": { "DecodeError": 1, "AnnotationMissing": 1, "FrameExtraction": 1, "SourceUnavailable": 1, "ResourceExhausted": 1, "AttemptTimeout": 1 },
    "backoff": { "max_backoff_ms": 0 },
    "attempt_timeout_ms": 600000,
    "run_wall_time_budget_ms": 3600000,
    "infrastructure_failure_storm_threshold": 2
  },
  "thresholds": { "min_coverage_ratio": 1.0, "max_class_failure_ratio": 0.1, "max_split_accepted_ratio_variance": 0.0, "max_replacement_ratio": 0.0 },
  "declared_threshold_digest": "343eb2b12236e6984358603780f16fd03c23a07ccd199f04d6a404ebbd350142",
  "declared_expected_sample_id_digest": "1b442df4911573935107a07e6cda5dafccc5832c09d7a8d38b6475be6ef47fc3",
  "replacement_policy": "forbidden"
}

PowerShell

Get-Content -Raw dataset-initialize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

cat dataset-initialize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

issue

What it does
Use issue to produce this result: attempt 1 and its deadline are returned.
Prerequisites
Required: the file initialized above and dataset-issue.json.
Expected result
Result: attempt 1 and its deadline are returned.
If it does not work
If it fails: initialize first and use the exact sample id.
{"action":"issue","canonical_sample_id":"private-video","requested_position":0}

PowerShell

Get-Content -Raw dataset-issue.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

cat dataset-issue.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

report

What it does
Use report to produce this result: the accepted sample is recorded.
Prerequisites
Required: the attempt returned by issue and dataset-report.json.
Expected result
Result: the accepted sample is recorded.
If it does not work
If it fails: use the attempt number returned by issue before its deadline.
{"action":"report","canonical_sample_id":"private-video","attempt":1,"outcome":"Accepted"}

PowerShell

Get-Content -Raw dataset-report.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

cat dataset-report.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

sweep

What it does
Use sweep to produce this result: expired attempts are counted and cleared.
Prerequisites
Required: an initialized progress file.
Expected result
Result: expired attempts are counted and cleared.
If it does not work
If it fails: check the output path and JSON spelling.
{"action":"sweep"}

PowerShell

'{"action":"sweep"}' | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

printf '%s' '{"action":"sweep"}' | godd-a dataset coverage --ledger .godd/dataset-coverage.json

finalize

What it does
Use finalize to produce this result: the final coverage result is returned.
Prerequisites
Required: all expected samples reported and dataset-finalize.json.
Expected result
Result: the final coverage result is returned.
If it does not work
If it fails: use exactly the same thresholds and digests as initialize.
{"action":"finalize","thresholds":{"min_coverage_ratio":1.0,"max_class_failure_ratio":0.1,"max_split_accepted_ratio_variance":0.0,"max_replacement_ratio":0.0},"replacement_policy":"forbidden","declared_threshold_digest":"343eb2b12236e6984358603780f16fd03c23a07ccd199f04d6a404ebbd350142","declared_expected_sample_id_digest":"1b442df4911573935107a07e6cda5dafccc5832c09d7a8d38b6475be6ef47fc3"}

PowerShell

Get-Content -Raw dataset-finalize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json

Bash / zsh

cat dataset-finalize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.json
godd-a gateway doctor [--no-probe]Checks the configured connection and whether it responds.
What it does
Checks the configured connection and whether it responds.
When to use it
Use it when enabling a connection or investigating why it is unavailable.
Prerequisites
Set GODD_PROVIDER_GATEWAY_URL when using a gateway.
Expected result
A secret-free configuration and connectivity report is shown.
If it does not work
If the connection fails, confirm that GODD_PROVIDER_GATEWAY_URL is the correct HTTPS endpoint, then check endpoint health and network reachability.

Copy-ready example

godd-a gateway doctor
godd-a plan audit <record|verify> [...]Records or verifies interruption, resume, and deviation evidence.
What it does
Records or verifies interruption, resume, and deviation evidence.
When to use it
Use it after interrupting, resuming, or departing from an approved plan.
Prerequisites
An active approved plan and GODD_LICENSE_KEY are required.
Expected result
The saved record is verified or a safe failure reason is returned.
If it does not work
If verification fails, confirm that the same run ID and license are in use. After rotating a license, begin continued work under a new run ID.

Copy-ready example

godd-a plan audit verify

How to use each action

record

What it does
Use record to produce this result: the interruption is recorded.
Prerequisites
Required: an active approved plan and GODD_LICENSE_KEY.
Expected result
Result: the interruption is recorded.
If it does not work
If it fails: confirm the plan is active and --event is interrupted, resumed, or plan-deviation.
godd-a plan audit record --event interrupted --reason-code user_pause --expected-step test --actual-step test

verify

What it does
Use verify to produce this result: the saved history is verified.
Prerequisites
Required: the same project and license used when recording.
Expected result
Result: the saved history is verified.
If it does not work
If it fails: confirm the active plan and license have not changed.
godd-a plan audit verify
godd-a research <start|checkpoint|status|complete|abort> [options]Stores and inspects minimal checkpoints for resumable research.
What it does
Stores and inspects minimal checkpoints for resumable research.
When to use it
Use it when a long investigation spans sessions.
Prerequisites
Prepare a sanitized summary and public HTTPS sources.
Expected result
Research state is returned as JSON without raw content or secrets.
If it does not work
If a session is not found, pass its exact ID to status. If saving is rejected, remove secrets from the summary and use only public HTTPS source URLs.

Copy-ready example

godd-a research start --session research-1 --topic "API retry policy"

How to use each action

start

What it does
Use start to produce this result: a new research session is created.
Prerequisites
Required: a unique session name and a non-sensitive topic.
Expected result
Result: a new research session is created.
If it does not work
If it fails: choose a session name that is not already active.
godd-a research start --session research-1 --topic "API retry policy"

checkpoint

What it does
Use checkpoint to produce this result: the checkpoint is saved.
Prerequisites
Required: an active session, a short summary, and an optional public HTTPS source.
Expected result
Result: the checkpoint is saved.
If it does not work
If it fails: remove private text and use a public HTTPS source without query parameters.
godd-a research checkpoint --session research-1 --summary "Retry rules confirmed" --source https://example.com/retry

status

What it does
Use status to produce this result: the current summary and state are shown.
Prerequisites
Required: an existing session name.
Expected result
Result: the current summary and state are shown.
If it does not work
If it fails: check the session name returned by start.
godd-a research status --session research-1

complete

What it does
Use complete to produce this result: the session is marked complete.
Prerequisites
Required: an active session whose investigation is finished.
Expected result
Result: the session is marked complete.
If it does not work
If it fails: save the final checkpoint before completing.
godd-a research complete --session research-1

abort

What it does
Use abort to produce this result: the session is marked aborted.
Prerequisites
Required: an active session and a non-sensitive reason code.
Expected result
Result: the session is marked aborted.
If it does not work
If it fails: provide both --session and --reason.
godd-a research abort --session research-1 --reason superseded
godd-a operate [--session=<id>] [--timeout-ms=<ms>] -- <program> [args...]Runs a user-selected program with state and a deadline.
What it does
Runs a user-selected program with state and a deadline.
When to use it
Use it for machine-operated agents that emit JSON or NDJSON.
Prerequisites
Confirm the program and its JSON/NDJSON output contract.
Expected result
JSON reports the turn, completion state, and exit code only.
If it does not work
If the child program fails, run it alone and confirm that stdout is newline-terminated JSON/NDJSON; increase the timeout when legitimate execution takes longer.

Copy-ready example

godd-a operate --timeout-ms=30000 -- node worker.mjs
godd-a shard partition <plan|lease|report|expire|abandon|status> [options]Creates divided work and manages reservations, results, expiry, abandonment, and status.
What it does
Creates divided work and manages reservations, results, expiry, abandonment, and status.
When to use it
Use it to divide large work without duplicate ownership and track workers.
Prerequisites
Confirm the existing shard plan state directory. Plan creation also requires a source root and N/M selector.
Expected result
Machine-readable JSON reports current shard and lease state.
If it does not work
If a lease or report is rejected, fetch the latest status and rebuild the input with its generation, revision, assigned shard, and current lease values.

Copy-ready example

godd-a shard partition status --state-dir .godd/shard-state

How to use each action

plan

What it does
Use plan to produce this result: a two-part work plan is created.
Prerequisites
Required: an existing source directory and an unused state directory.
Expected result
Result: a two-part work plan is created.
If it does not work
If it fails: check that --selector is N/M and the source directory is inside the project.
godd-a shard partition plan --state-dir .godd/shards --source-root data --selector 1/2

lease

What it does
Use lease to produce this result: part 1 is reserved for 60 seconds and saved for report.
Prerequisites
Required: an existing plan and an available part.
Expected result
Result: part 1 is reserved for 60 seconds and saved for report.
If it does not work
If it fails: run status and wait for or explicitly take over an expired reservation.
godd-a shard partition lease --state-dir .godd/shards --selector 1/2 --ttl-ms 60000

PowerShell

godd-a shard partition lease --state-dir .godd/shards --selector 1/2 --ttl-ms 60000 | Set-Content -Encoding utf8NoBOM shard-lease.json

Bash / zsh

godd-a shard partition lease --state-dir .godd/shards --selector 1/2 --ttl-ms 60000 > shard-lease.json

report

What it does
Use report to produce this result: the completed item is recorded.
Prerequisites
Required: shard-lease.json saved from the lease output.
Expected result
Result: the completed item is recorded.
If it does not work
If it fails: save the newest lease output to shard-lease.json and retry before it expires.
{"plan_generation":{"source_generation":"<plan output>","expected_set_digest":"<plan output>"},"sequence_id":"<lease assigned_ids[0]>","reporting_shard_index":1,"lease_generation":1,"expected_state":"assigned","expected_ledger_revision":0,"outcome":"completed"}

PowerShell

node -e "const l=require('./shard-lease.json');process.stdout.write(JSON.stringify({plan_generation:l.plan_generation,sequence_id:l.assigned_ids[0],reporting_shard_index:l.shard_index,lease_generation:l.lease_generation,expected_state:'assigned',expected_ledger_revision:l.ledger_revision,outcome:'completed'}))" | godd-a shard partition report --state-dir .godd/shards

Bash / zsh

node -e "const l=require('./shard-lease.json');process.stdout.write(JSON.stringify({plan_generation:l.plan_generation,sequence_id:l.assigned_ids[0],reporting_shard_index:l.shard_index,lease_generation:l.lease_generation,expected_state:'assigned',expected_ledger_revision:l.ledger_revision,outcome:'completed'}))" | godd-a shard partition report --state-dir .godd/shards

expire

What it does
Use expire to produce this result: expired reservations are released.
Prerequisites
Required: an existing plan.
Expected result
Result: expired reservations are released.
If it does not work
If it fails: check the state directory and retry after the reservation deadline.
godd-a shard partition expire --state-dir .godd/shards

abandon

What it does
Use abandon to produce this result: the reservation is returned for reassignment.
Prerequisites
Required: a reservation owned by the selected part.
Expected result
Result: the reservation is returned for reassignment.
If it does not work
If it fails: use the same selector that acquired the reservation.
godd-a shard partition abandon --state-dir .godd/shards --selector 1/2

status

What it does
Use status to produce this result: current progress and remaining items are shown.
Prerequisites
Required: an existing plan.
Expected result
Result: current progress and remaining items are shown.
If it does not work
If it fails: create the plan first or correct --state-dir.
godd-a shard partition status --state-dir .godd/shards
godd-a realtime <admission|admission-dev> --evaluated-at-ms <u64>Decides whether realtime processing may start using the supplied time.
What it does
Decides whether realtime processing may start using the supplied time.
When to use it
Use it immediately before starting a production or development realtime worker.
Prerequisites
Pipe the event JSON shown below to stdin and supply the current Unix epoch milliseconds.
Expected result
The command returns whether processing may start and, if not, why.
If it does not work
If admission is denied, inspect the returned reason, generate requested_at and evaluated-at-ms from the same current time, and refresh the deadline and evidence generation.

Copy-ready example

godd-a realtime admission --evaluated-at-ms ([DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds())

PowerShell

$nowMs = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds(); node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" $nowMs | godd-a realtime admission --evaluated-at-ms $nowMs

Bash / zsh

now_ms="$(node -p Date.now())"; node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" "$now_ms" | godd-a realtime admission --evaluated-at-ms "$now_ms"

How to use each action

admission

What it does
Use admission to produce this result: ALLOW or a clear rejection reason is returned.
Prerequisites
Required: the generated event JSON and current UTC time.
Expected result
Result: ALLOW or a clear rejection reason is returned.
If it does not work
If it fails: generate requested_at and evaluated-at-ms from the same current time and validate every fingerprint.
godd-a realtime admission --evaluated-at-ms $nowMs

PowerShell

$nowMs = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds(); node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" $nowMs | godd-a realtime admission --evaluated-at-ms $nowMs

Bash / zsh

now_ms="$(node -p Date.now())"; node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" "$now_ms" | godd-a realtime admission --evaluated-at-ms "$now_ms"

admission-dev

What it does
Use admission-dev to produce this result: the development entry point returns the same decision.
Prerequisites
Required: the generated event JSON and current UTC time in development.
Expected result
Result: the development entry point returns the same decision.
If it does not work
If it fails: fix the generated event before starting the development worker.
godd-a realtime admission-dev --evaluated-at-ms $nowMs

PowerShell

$nowMs = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds(); node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" $nowMs | godd-a realtime admission-dev --evaluated-at-ms $nowMs

Bash / zsh

now_ms="$(node -p Date.now())"; node -e "const n=Number(process.argv[1]);const h='a'.repeat(64);const requested=new Date(Math.floor(n/1000)*1000).toISOString().replace('.000Z','Z');process.stdout.write(JSON.stringify({schema_version:1,principal_fingerprint:'principal:sha256:'+h,resource_id:'resource:sha256:'+h,resource_generation:7,action:'player:join',evidence:[{kind:'membership',generation:7,outcome:'present',evidence_fingerprint:'evidence:sha256:'+h}],policy_generation:3,requested_at:requested,deadline_ms:60000}))" "$now_ms" | godd-a realtime admission-dev --evaluated-at-ms "$now_ms"
godd-a versionShows the installed version and checks for updates.
What it does
Shows the installed version and checks for updates.
When to use it
Use it for diagnosis, before updating, or before contacting support.
Prerequisites
Install GoDD MCP α globally first.
Expected result
The current version and, when reachable, the latest version are shown.
If it does not work
If the latest release cannot be retrieved, check the network and proxy settings. The displayed installed version is still usable as environment information.

Copy-ready example

godd-a version
godd-a skills [candidates|promote <name>|demote <name>]Lists reusable candidates and promotes or demotes project knowledge.
What it does
Lists reusable candidates and promotes or demotes project knowledge.
When to use it
Use it to manage knowledge that should be reused across work.
Prerequisites
Complete godd-a init in the target project.
Expected result
Candidates or the promote/demote result are returned.
If it does not work
If a candidate or skill is not found, run from the project root, copy its exact name from candidates, and retry promote or demote.

Copy-ready example

godd-a skills candidates

How to use each action

candidates

What it does
Use candidates to produce this result: eligible and blocked skills are listed.
Prerequisites
Required: a project containing personal skills.
Expected result
Result: eligible and blocked skills are listed.
If it does not work
If it fails: run the command from the project root.
godd-a skills candidates

promote

What it does
Use promote to produce this result: the skill becomes project-wide.
Prerequisites
Required: an eligible personal skill name from candidates.
Expected result
Result: the skill becomes project-wide.
If it does not work
If it fails: resolve every BLOCKED reason before retrying.
godd-a skills promote api-review

demote

What it does
Use demote to produce this result: the skill returns to personal scope.
Prerequisites
Required: a project skill that can return to personal scope.
Expected result
Result: the skill returns to personal scope.
If it does not work
If it fails: confirm the exact skill name and its current scope.
godd-a skills demote api-review

Troubleshooting

First verify the installation and restart your client.

The command is not found

Run godd-a version, repeat godd-a install if needed, then restart the MCP client.

godd-a version

No extra audit key

Plan audit normally works with your current license key. No additional key setup is required.

License and support

Review plans, license issuance, and available support on the pricing page.