Skip to content

user-guide.md

Latest commit

 

History

History
894 lines (664 loc) · 28.2 KB

user-guide.md

File metadata and controls

894 lines (664 loc) · 28.2 KB

Samourai Devkit User Guide

This guide covers the installation and use of Samourai Devkit in an existing software project. It is intended for technical users who want to understand the real scope of the kit, its artifacts, its limitations, and its operating model.

Scope

Samourai Devkit installs an AI-assisted working framework inside a Git repository:

  • specialized agents;
  • workflow commands;
  • prompts;
  • skills;
  • governance conventions;
  • documentation templates;
  • adapters for OpenCode and VS Code/GitHub Copilot.

The kit does not provide a hosted service, an autonomous orchestration engine, or a guarantee of identical execution across editors. It installs files into a target project; execution then depends on the environment used, local configuration, available tooling, and human validations.

Samourai Devkit does not replace architectural responsibility, review, or validation. It structures work and makes deliverables more explicit:

  • change scoping;
  • specification;
  • test plan;
  • implementation plan;
  • controlled execution;
  • review;
  • quality checks;
  • documentation synchronization;
  • commit and PR/MR.

Installation Model

Samourai separates kit resources, project artifacts, and temporary traces.

Core

The core contains the reusable reference resources of the kit:

core/agents/
core/commands/
core/skills/
core/governance/
core/templates/
core/decisions/

In a target project, the script installs the following reference resources under .samourai/core/:

.samourai/core/governance/
.samourai/core/templates/
.samourai/core/decisions/

Source agents, commands, and skills remain in the kit repository. They are rendered or copied into the chosen editor adapter.

Editor Adapters

An adapter converts Samourai sources into the format expected by a given editor.

OpenCode:

.opencode/agent/
.opencode/command/
.opencode/skills/
.opencode/opencode.jsonc

VS Code/GitHub Copilot:

.github/agents/
.github/prompts/
.github/skills/
.github/copilot-instructions.md
.vscode/settings.json
.vscode/mcp.json

Blueprints:

.samourai/blueprints/

Blueprints are structural references used by /bootstrap, /generate-project-skills, /write-test-plan, /review, /pr, and @toolsmith. They guide the shape of generated artifacts without granting additional write permissions to commands.

Project Artifacts

Documents produced during workflows go under .samourai/docai/:

.samourai/docai/changes/
.samourai/docai/spec/
.samourai/docai/decisions/
.samourai/docai/planning/

Temporary files produced by agents go under .samourai/tmpai/:

.samourai/tmpai/run-logs-runner/
.samourai/tmpai/code-review/
.samourai/tmpai/review-feedback/
.samourai/tmpai/pr/

The project profile generated by /bootstrap goes under:

.samourai/ai/agent/project-profile.md

It indicates whether the project is in TMA, Build, Guide, or Mix mode. Agents use it to adapt plans, development, fixes, reviews, and result presentation. For example: in TMA mode, they limit the scope of changes and highlight regression risk; in Build mode, they emphasize deliverable increments, tests, and compatibility.

.samourai/AGENTS.md is not copied from the kit. It must be generated by /bootstrap in the target project, as its content depends on the real context of the repository. A minimal AGENTS.md can also be generated at the root for tools that automatically load this file; it must point to .samourai/AGENTS.md.

Installation Manifest

The script maintains local state under:

.samourai/install/installed-files.txt
.samourai/install/overwritten-files.txt
.samourai/install/installed-files.sha256
.samourai/install/last-install-summary.txt

The manifest enables uninstalling the added files. Checksums prevent automatically removing a file that was installed and then locally modified.

Installation

Prerequisites

  • For local mode, run the script from the samourai-devkit repository.
  • Target an existing Git project.
  • Use --allow-non-root only when installing into a Git subdirectory is intentional.
  • Have OpenCode or VS Code/GitHub Copilot ready depending on the chosen adapter.

Remote Installation from GitHub

To install without manually cloning the repository:

curl -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --target /path/to/project

The remote script downloads the GitHub archive into a temporary folder, then runs the local script scripts/install-samourai.sh with the provided options. Installation behavior is therefore identical to the local script: manifest, checksums, editor options, dry-run, --force, and uninstall.

Examples:

curl -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --target /path/to/project --editor opencode
curl -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --target /path/to/project --editor vscode --skip-opencode
curl -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --target /path/to/project --core-only

To pin the version used:

curl -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --ref v1.0.0 -- --target /path/to/project

For a private repository, do not pass the token in the URL. Use an Authorization header and expose the token to the script via SAMOURAI_GITHUB_TOKEN, so that the GitHub archive download uses the same authentication:

read -rsp 'GitHub token: ' SAMOURAI_GITHUB_TOKEN; echo
export SAMOURAI_GITHUB_TOKEN
curl -H "Authorization: Bearer ${SAMOURAI_GITHUB_TOKEN}" -fsSL https://raw.githubusercontent.com/FR-PAR-SAMOUR-AI/samourai-devkit/main/scripts/install-remote.sh | bash -s -- --target /path/to/project --editor opencode
unset SAMOURAI_GITHUB_TOKEN

For production use, prefer a tag or a verified commit rather than the main branch.

Remote script options:

Option Usage
--repo <owner/repo> Download the kit from a different GitHub repository.
--ref <ref> Use a specific branch, tag, or commit. Recommended for production.
-- Separate remote options from options forwarded to the local script. Required when a local option could be confused with a remote option.

All other options are forwarded to scripts/install-samourai.sh.

Interactive Installation

./scripts/install-samourai.sh --interactive

Interactive mode prompts for:

  • the target project;
  • the editor adapter;
  • whether to install OpenCode;
  • whether to run as a dry-run;
  • confirmation before writing.

OpenCode Installation

./scripts/install-samourai.sh --target /path/to/project --editor opencode

By default, the OpenCode adapter is installed. If opencode is not available in the PATH, the script can launch the official installer:

curl -fsSL https://opencode.ai/install | bash

To skip this automatic installation:

./scripts/install-samourai.sh --target /path/to/project --editor opencode --skip-opencode

VS Code/GitHub Copilot Installation

./scripts/install-samourai.sh --target /path/to/project --editor vscode --skip-opencode

The VS Code adapter generates custom agents, prompt files, skills, Copilot instructions, and the VS Code/MCP configuration. Subagent behavior depends on the VS Code and Copilot versions and available experimental features.

OpenCode and VS Code Installation

./scripts/install-samourai.sh --target /path/to/project --editor all

Core-only Installation

./scripts/install-samourai.sh --target /path/to/project --core-only

This mode installs only the reference resources under .samourai/core/. It does not install any agents or commands that can be used directly in an editor.

Diagnostics

./scripts/install-samourai.sh --target /path/to/project --doctor

The diagnostic checks for:

  • presence of a Git repository;
  • the Samourai core;
  • the manifest;
  • OpenCode/VS Code adapters;
  • main configuration files;
  • presence of .samourai/AGENTS.md or the root entry point AGENTS.md.

Dry-run and Overwrite

Preview:

./scripts/install-samourai.sh --target /path/to/project --dry-run

Overwrite existing Samourai files:

./scripts/install-samourai.sh --target /path/to/project --force

Without --force, an existing file is preserved, is not added to the manifest, and will not be removed by uninstallation.

With --force, overwritten paths are recorded in .samourai/install/overwritten-files.txt. This file is an audit log; it does not contain backups.

Installation Options Reference

Option When to use
--target <dir> Install into a specific target project. Default: current directory.
--source <dir> Use a different local copy of the kit. Rare; useful for testing or forking.
--editor opencode Install OpenCode adapter only. This is the default.
--editor vscode Install VS Code/GitHub Copilot adapter only. Add --skip-opencode.
--editor all or --editor opencode,vscode Install both adapters.
--core-only Install only .samourai/core/ and .samourai/blueprints/, without usable commands or agents.
--symlink-stack Install the stack into a sibling <project>-samurai folder and create .opencode / .samourai symlinks in the target project.
--stack-dir <dir> Explicitly choose the stack folder used by --symlink-stack.
--skip-opencode Do not run the OpenCode installer even when the OpenCode adapter is requested.
--interactive Let the script prompt for the target project, editor, and preview.
--doctor Diagnose an existing installation without writing any files.
--dry-run or -n Preview writes. Use before a first installation or before --force.
--force or -f Replace already-present files. Use after reviewing the dry-run or to update the adapter.
--allow-non-root Allow installation into a Git subdirectory. Avoid unless intentional.
--list-editors Print supported adapters and exit.
--verbose or -v Enable debug logs.
--help, --version Print help or the script version.

Project Initialization

After installation, open the target project in the chosen environment.

With OpenCode:

opencode

Then run:

/bootstrap

or, if the detected name might be ambiguous:

/bootstrap my-billing-service

Bootstrap analyzes the project and generates the initial project artifacts, including .samourai/AGENTS.md and, if necessary, a minimal root AGENTS.md. This step must be reviewed: the generated project context becomes a structural input for all agents.

/bootstrap is a multi-session command. It resumes its state from .samourai/ai/local/bootstrapper-context.yaml if that file exists. The actual flow is:

scan -> assess -> interview -> mcp-setup -> draft -> review -> write

The first question must establish the artifact language; bootstrap then asks any remaining questions. The mcp-setup phase may adjust .opencode/opencode.jsonc to enable relevant detected MCPs. The bootstrapper must not modify application code, must not store secrets, and is restricted to its defined project write paths.

Default generated artifacts:

  • AGENTS.md, minimal root entry point;
  • .samourai/AGENTS.md, main project instructions;
  • .samourai/ai/agent/pm-instructions.md, backlog/tracker configuration;
  • .samourai/ai/agent/pr-instructions.md, PR/MR configuration;
  • .samourai/ai/agent/project-profile.md, TMA, Build, Guide, or Mix profile;
  • .samourai/docai/documentation-handbook.md, if the repository needs it.

Artifacts generated only when context justifies it or when the user requests them: overview, feature specs, non-functional spec, project guides, project templates, decisions, local backlog, epics, and archive. None of these artifacts should be treated as authoritative without human review.

To generate project-specific skills:

/generate-project-skills

This command should remain focused. The kit intentionally limits generation to small batches to avoid generic or unverified skills.

Standard Workflow

A change tracked by Samourai generally follows this order:

/analyze-user-stories <ref>
/plan-change <ref>
/extract-us-from-doc
/write-spec <ref>
/write-test-plan <ref>
/write-plan <ref>
/run-plan <ref>
/gap-analysis <ref>
/review <ref>
/check
/verdict <ref>
/sync-docs <ref>
/commit
/pr

For a GitHub issue:

/analyze-user-stories GH-123
/plan-change GH-123
/extract-us-from-doc
/write-spec GH-123
/write-test-plan GH-123
/write-plan GH-123
/run-plan GH-123
/gap-analysis GH-123
/review GH-123
/check
/verdict GH-123
/sync-docs GH-123
/commit
/pr

/test-api-e2e should be added only when the project has a compatible backend/API workflow and the change justifies it.

Orchestration can also be delegated to pm:

@pm deliver change GH-123

In this case, pm must scope, delegate, control deliverables, and escalate ambiguities. It must not hide risks or consider a phase complete without actionable evidence.

Agent Roles

An agent represents a workflow responsibility. Role boundaries matter: they prevent an agent from modifying code, documentation, or Git outside its scope.

Agent Responsibility
bootstrapper Analyzes the target project and generates initialization artifacts.
pm Orchestrates the change, clarifies scope, delegates, and tracks progress.
architect Analyzes technical decisions, structural impacts, and trade-offs.
spec-writer Produces or updates the specification for a change.
test-plan-writer Produces the test plan linked to the specification.
plan-writer Produces the implementation plan.
coder Implements tasks validated in the plan.
tdd-orchestrator Frames a test-first cycle when the change calls for it.
runner Executes commands and returns useful results.
reviewer Verifies the change against the spec, plan, and repository rules.
code-reviewer Deepens the code review: security, reliability, performance, maintainability.
fixer Reproduces and fixes a targeted issue.
doc-syncer Synchronizes documentation after an accepted change.
committer Prepares a Conventional Commit.
pr-manager Prepares or updates a PR/MR.
review-feedback-applier Processes accepted review feedback.
designer Works on interfaces and user experience.
editor Improves text content and phrasing.
external-researcher Searches for external information using available tools.
image-generator Generates images if the image tool is installed and configured.
image-reviewer Analyzes screenshots, images, and visual outputs.
toolsmith Evolves Samourai agents, commands, or skills.
gap-analysis Compares spec, plan, tests, and implementation to identify lifecycle coverage gaps.
verdict Produces a GO/NO-GO readiness verdict based on quality and traceability evidence.
refactor Plans and executes safe refactoring while preserving behavior and validating with tests.
jira-analysis Analyzes tickets/user stories for completeness and extracts structured requirements.

Typical usage:

pm -> spec-writer -> test-plan-writer -> plan-writer -> coder -> runner -> reviewer

Targeted examples:

@runner run npm test and summarize failures
@reviewer review GH-123 against the spec and plan
@coder implement phase 1 of GH-123

Practical rule:

  • use a /... command when the workflow must resolve paths, load blueprints, apply the project profile, or write the expected artifact;
  • call an @... agent directly for a targeted, already-contextualized task, or when a human is manually orchestrating steps;
  • use @pm when the change spans multiple roles and the ticket or backlog must remain the entry point;
  • use @runner for long or log-heavy commands, to preserve logs under .samourai/tmpai/run-logs-runner/;
  • use @committer or /commit for all commits; other agents must not bypass the Conventional Commit format.

Available Commands

Command Usage Options and use cases
/bootstrap [project-name] Initialize Samourai in an existing project. Add project-name if the repository name is not descriptive enough. Resumes local state if a bootstrap is already in progress.
/plan-change [ref] [idea] Scope a change before specification. Without ref, the command helps choose or create the reference. With free text, it uses it as initial context. Does not write any files.
/write-spec <ref> Generate or update the specification. Requires a scoping context. Creates the .samourai/docai/changes/... folder if absent and writes only chg-<ref>-spec.md.
/write-test-plan <ref> [options] Generate or update the test plan. Free options such as focus=backend, nfr-only, no-manual. Requires the spec and .samourai/ai/rules/testing-strategy.md.
/write-plan <ref> Generate or update the implementation plan. Requires the spec. Reads the project profile if present. Writes only chg-<ref>-plan.md.
/run-plan <ref> [directives] Execute planned tasks. Directives: execute next N phases, execute all remaining phases, execute phase N, dry run, no review, commit per task. Default: one phase then review pause.
/tdd <ref> [scope] Execute a task in test-first mode. scope: phase N, next task, or free description. Use when red-green-refactor order matters.
/review <ref> [directives] Review a change against the spec, plan, and repository rules. Directives: dry run, preview only, base=<branch>, head=<ref>, no commit. Adds a remediation phase if needed.
/check [fast/slow/all/gate...] [--skip-autofix] [--dry-run] Run quality gates without automatic fixes. Passes arguments to the quality script resolved from .samourai/AGENTS.md or ./scripts/quality-gates.sh.
/check-fix Run quality gates and fix detected issues. Use after a reproducible failure or before delivery when targeted automatic fixes are acceptable. Ends with a commit via @committer.
/sync-docs <ref> [directives] Synchronize documentation after a change. Directives: dry run, contracts only, force, no commit, base=<branch>. Run after an accepted change or with force.
/commit [intent] Create a Conventional Commit. Intent is optional and serves as a hint for the message. Never pushes.
/pr [args] Create or update a PR/MR. Uses instructions from .samourai/ai/agent/pr-instructions.md and writes the description under .samourai/tmpai/pr/<branch>/. Never merges.
/git-workflow <target-branch> [flags] Drive the complete Git flow with user checkpoints. Flags: --skip-tests, --draft-pr, --no-push, --conventional, --dry-run. Use at end of delivery for a single controlled review, test, commit, push, and PR flow.
/generate-project-skills [directives] Generate project-specific skills. Directives: dry run, preview only, refresh, max=1..3, domain=<name>, focus=run,test,architecture,build,review,debug,migration,ci.
/test-api-e2e [fast/all/target] [--dry-run] Run backend/API E2E tests configured in the repository. Add only if the repository exposes an API E2E workflow. Fails with NEEDS_INPUT if no command is detected.
/analyze-user-stories <ref> Analyze user stories for completeness and delivery readiness. Use before specification to validate requirements and identify missing acceptance details.
/extract-us-from-doc Extract structured user stories from business documentation. Use when requirements are in prose and need normalized stories before planning/specification.
/gap-analysis <ref> Analyze gaps across spec, plan, tests, and code. Use after implementation and before review/final validation.
/verdict <ref> Produce a GO/NO-GO readiness verdict for a change. Use after checks/review as the final decision gate before PR creation.

Available Skills

The following skill packs are available to support the new analysis and delivery workflow:

Skill Purpose
user-story-analysis Analyze user stories for quality, completeness, and implementation readiness.
us-from-document Convert business documents into structured user stories and acceptance criteria.
spec-generation Accelerate specification drafting from validated requirements.
test-plan-generation Build traceable test plans aligned with acceptance criteria.
code-analysis Analyze code structure, quality signals, and implementation consistency.
gap-analysis Compare lifecycle artifacts to detect traceability and coverage gaps.
verdict-decision Produce evidence-based GO/NO-GO readiness verdicts.
refactoring Guide safe, incremental refactoring with behavior-preserving checks.
documentation-generation Generate or update documentation artifacts from implementation evidence.

When in doubt, start with:

/plan-change <ref>

or ask explicitly for guidance:

@pm explain the next step for GH-123

Using with OpenCode

OpenCode is the primary adapter for the kit. It supports agents, commands, and skills installed under .opencode/.

Installation:

./scripts/install-samourai.sh --target /path/to/project --editor opencode

Launch in the target project:

opencode

Common commands:

/bootstrap
@pm deliver change GH-123

Commands that modify the repository (/run-plan, /check-fix, /commit, /pr, etc.) must be treated as effective operations on the target project. Review diffs and produced artifacts before validating.

Using with VS Code/GitHub Copilot

The VS Code adapter installs:

  • agents under .github/agents/;
  • prompts under .github/prompts/;
  • skills under .github/skills/;
  • Copilot instructions under .github/copilot-instructions.md;
  • configuration under .vscode/.

Installation:

./scripts/install-samourai.sh --target /path/to/project --editor vscode --skip-opencode

Depending on the environment, agents may appear in the Copilot selector. If not, use the prompt files directly.

VS Code Subagents

VS Code/Copilot subagents depend on experimental features. Samourai declares delegation relationships to align with the OpenCode model, for example:

pm -> coder -> runner
pm -> reviewer -> fixer
coder -> tdd-orchestrator -> runner

This behavior is not guaranteed by the kit. If automatic delegation is not available, execute the workflow manually:

1. Use the write-spec prompt.
2. Select the test-plan-writer agent.
3. Select the plan-writer agent.
4. Select the coder agent.
5. Select the runner agent.
6. Select the reviewer agent.

Change Example

Issue:

GH-123: Add a GET /health endpoint

Scoping

/plan-change GH-123

Scoping must specify:

  • the expected behavior;
  • the response format;
  • the files or modules involved;
  • the expected tests;
  • the boundaries of the change.

Specification

/write-spec GH-123

Expected deliverable:

.samourai/docai/changes/YYYY-MM/YYYY-MM-DD--GH-123--health-endpoint/chg-GH-123-spec.md

Test Plan

/write-test-plan GH-123

Example cases:

  • GET /health returns 200;
  • the response contains status: "ok";
  • a test fails if the endpoint is removed or its contract changes.

Implementation Plan

/write-plan GH-123

The plan must be broken into verifiable tasks. Example:

1. Add the endpoint test.
2. Add the route.
3. Verify the JSON contract.
4. Run the tests.
5. Update documentation if needed.

Execution

/run-plan GH-123

or:

@coder implement GH-123 from the plan

Review and Checks

/review GH-123
/check

On a reproducible failure:

/check-fix

Commit and PR

/commit
/pr

Before validating, verify:

  • the Git diff;
  • .samourai/docai/ artifacts;
  • executed tests;
  • documented limitations or exceptions;
  • any out-of-scope files.

Best Practices

  • Start with small, verifiable changes.
  • Require a specification before implementation when the change has a functional or architectural impact.
  • Do not let agents invent missing business rules.
  • Keep plans short and auditable.
  • Review generated artifacts before treating them as a source of truth.
  • Do not confuse prompt success with technical validation.
  • Explicitly document unexecuted tests or manual validations.
  • Use toolsmith to evolve Samourai itself, not to modify the target application directly.

Clarification request:

@pm clarify GH-123 before implementation

External research:

@external-researcher research the official FastAPI documentation for dependency injection and summarize what matters for GH-123

Image generation:

@image-generator generate a clean dashboard hero image for a SaaS project, save it to assets/hero-dashboard.avif

If the image tool is not installed or configured, the agent must stop and report this. It must not claim to have generated an asset.

Troubleshooting

Invalid OpenCode Configuration

Check the generated file:

cat .opencode/opencode.jsonc

Reinstall the adapter if needed:

./scripts/install-samourai.sh --target /path/to/project --editor opencode --force

Missing VS Code Agents

Check the files:

.github/agents/*.agent.md
.github/prompts/*.prompt.md
.github/copilot-instructions.md

Restart VS Code. If agents are still unavailable, use the prompt files manually.

Unavailable VS Code Subagents

Use the manual workflow:

pm -> spec-writer -> test-plan-writer -> plan-writer -> coder -> runner -> reviewer

Previewing an Installation

./scripts/install-samourai.sh --target /path/to/project --dry-run

Uninstalling

./scripts/uninstall-samourai.sh --target /path/to/project

Uninstallation follows the local manifest when it exists. It may remove:

  • files listed in .samourai/install/installed-files.txt;
  • remaining dedicated Samourai folders after confirmation: .opencode, .samourai/tmpai, .samurai, and former root-level .docai/.tmpai;
  • certain legacy Samourai files in .ai;
  • local state under .samourai/ai/local/.

It never fully removes:

  • .github;
  • .vscode;
  • .ai.

If the script displays:

Remaining folder: .opencode
Remove this folder? Type "supprime" to confirm

removal requires the exact input:

supprime

Empty input: the folder is preserved.

Non-interactive removal of dedicated Samourai folders:

./scripts/uninstall-samourai.sh --target /path/to/project --force

Even with --force, .github, .vscode, .ai, .samourai/docai, .samourai/ai/{agent,rules,context}, and .samourai/AGENTS.md are not fully removed.

Uninstall options:

Option When to use
--target <dir> Uninstall from a specific target project. Default: current directory.
--dry-run or -n Preview removals without deleting. Recommended before any uninstall.
--force or -f Remove dedicated Samourai folders without prompting for supprime confirmation.
--allow-non-root Allow uninstall from a Git subdirectory. Avoid unless intentional.
--verbose or -v Enable debug logs.
--help, --version Print help or the script version.

Before uninstalling, verify the target path:

pwd -P
ls -la /path/to/project
./scripts/uninstall-samourai.sh --target /path/to/project --dry-run

The script acts only on --target. If multiple copies of a project exist, the path must point to the one that actually contains .opencode, .samourai, .samourai/docai, or .samourai/tmpai.

Summary

For the orchestration closest to the model intended by the kit:

OpenCode + /bootstrap + @pm

To stay in VS Code:

VS Code + prompt files + custom agents

If VS Code subagents are available, they can improve workflow continuity. Otherwise, the workflow remains usable manually, provided that useful context is explicitly passed between agents and deliverables are reviewed.