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.
- Review plans and create an account
- Choose a subscription
- 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-alphagodd-a install --license-key=YOUR_LICENSE_KEYgodd-a init/godd-a/dev Add profile editingChoose 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.
Fix a defect safely
Trace impact, add a reproduction test, and verify that regressions are prevented.
Explain and share a change
Update user docs, review the result, and create a pull request.
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-insWhat to use next
/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/checkWhat to use next
/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/shipWhat 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/reviewWhat to use next
/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 retriesWhat 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/commitWhat 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/pushWhat 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/prWhat to use next
/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 productionWhat 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.0What 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 mainWhat 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 CLIWhat 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 logsWhat to use next
/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/mapWhat to use next
/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/diagramWhat 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.mdWhat 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 dashboardWhat 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:1wWhat to use next
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/checkWhat 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 projectWhat to use next
/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.tsWhat 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/configWhat 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/questionsWhat 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 flowWhat to use next
/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 conventionWhat to use next
/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/metricsWhat to use next
/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.mdWhat 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/checkPublic 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_KEYWhat to use next
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=engodd-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=cursorgodd-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 servegodd-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 compatibilitygodd-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-runnerWhat to use next
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 fixedWhat to use next
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.jsonInput 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.jsonBash / zsh
cat dataset-action.json | godd-a dataset coverage --ledger .godd/dataset-coverage.jsonHow 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.jsonBash / zsh
cat dataset-initialize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.jsonissue
- 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.jsonBash / zsh
cat dataset-issue.json | godd-a dataset coverage --ledger .godd/dataset-coverage.jsonreport
- 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.jsonBash / zsh
cat dataset-report.json | godd-a dataset coverage --ledger .godd/dataset-coverage.jsonsweep
- 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.jsonBash / zsh
printf '%s' '{"action":"sweep"}' | godd-a dataset coverage --ledger .godd/dataset-coverage.jsonfinalize
- 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.jsonBash / zsh
cat dataset-finalize.json | godd-a dataset coverage --ledger .godd/dataset-coverage.jsongodd-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 doctorWhat to use next
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 verifyHow 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 testverify
- 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 verifyWhat to use next
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/retrystatus
- 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-1complete
- 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-1abort
- 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 supersededgodd-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.mjsgodd-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-stateHow 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/2lease
- 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 60000PowerShell
godd-a shard partition lease --state-dir .godd/shards --selector 1/2 --ttl-ms 60000 | Set-Content -Encoding utf8NoBOM shard-lease.jsonBash / zsh
godd-a shard partition lease --state-dir .godd/shards --selector 1/2 --ttl-ms 60000 > shard-lease.jsonreport
- 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/shardsBash / 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/shardsexpire
- 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/shardsabandon
- 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/2status
- 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/shardsgodd-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 $nowMsBash / 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 $nowMsPowerShell
$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 $nowMsBash / 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 $nowMsPowerShell
$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 $nowMsBash / 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 versiongodd-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 candidatesHow 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 candidatespromote
- 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-reviewdemote
- 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-reviewWhat to use next
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 versionNo extra audit key
Plan audit normally works with your current license key. No additional key setup is required.