wingman

README: English | 日本語

wingman is a CLI package for decision-driven, issue-based AI development with local agents.

The package helps engineers use AI for implementation support without giving up the human parts of engineering: specification, decision-making, and review.

Current roles:

• mentor
• coder

Current runtime:

• codex

Install

npm install -g @yumat_512/wingman

or:

npx @yumat_512/wingman mentor

Usage

Start with Mentor:

wingman mentor
wingman mentor --new

Mentor helps turn a feature idea into a GitHub Issue-ready specification with explicit decisions. When used without an issue number, Wingman manages a pre-issue mentor spec artifact and reuses its saved Codex session when available.

Create a GitHub Issue from the reviewed spec file:

wingman issue create --file ./issue-spec.md
wingman issue create --file ./wingman-notes/mentor/spec-01.md
wingman issue create --title "Add login validation" --file ./issue-spec.md
wingman issue create --file ./issue-spec.md --yes

Then run Coder against an issue:

wingman coder --issue 123

Short issue syntax:

wingman coder 123

Generation-only mode:

wingman mentor --no-launch
wingman coder --issue 123 --no-launch

Pass Codex options after --:

wingman coder --issue 123 -- --model gpt-5

Issue comment workflow:

wingman coder 123
wingman coder 123 --new
wingman coder 123 --post

wingman mentor 123
wingman mentor 123 --new
wingman mentor 123 --post
wingman mentor 123 --post --file ./wingman-notes/mentor/issue-123-comment-02.md

wingman artifact create --role mentor --issue 123
wingman artifact create --role coder --issue 123 --new

Issue Spec

Wingman treats GitHub Issues as implementation specifications.

Expected sections:

• Background
• Goal
• Non-Goal
• Decision Log
• Acceptance Criteria
• Review Points
• Open Questions

coder --issue loads the issue and issue comments with gh issue view and includes them in the generated instruction.

issue create uses gh issue create. If --title is omitted, Wingman uses the first top-level # Title heading in the markdown file. Issue creation is blocked when Open Questions contains unresolved items. Before creating the issue, Wingman shows the target repository and asks for confirmation. Use --yes to skip the prompt.

Issue comment posting uses local markdown note files with YAML frontmatter. Wingman manages these files through .wingman/artifacts.json.

• wingman mentor selects the current pre-issue mentor spec artifact.
• wingman mentor --new creates the next pre-issue mentor spec artifact and marks it current.
• wingman <role> <issue> selects the current managed artifact for that issue and role.
• wingman <role> <issue> --new creates the next managed artifact file and marks it current.
• wingman <role> <issue> --post posts the current artifact by default.
• --file overrides the current artifact and posts an explicit markdown file.

Managed artifact naming:

• mentor pre-issue spec: wingman-notes/mentor/spec-<sequence>.md
• mentor: wingman-notes/mentor/issue-<issue>-comment-<sequence>.md
• coder: wingman-notes/coder/issue-<issue>-note-<sequence>.md

Manifest behavior:

• .wingman/artifacts.json tracks pre-issue mentor specs, issue artifacts, and saved Codex session ids.
• current means "the default artifact to continue editing or posting next".
• issue create parses the created issue URL, extracts the issue number, and binds it back to a managed mentor spec artifact when the body file matches.
• When a saved Codex session id exists, Wingman prefers codex resume <sessionId>.
• wingman mentor <issue> falls back to the bound pre-issue mentor session when the issue comment artifact has no saved session yet.
• <role> <issue> reuses current when it exists.
• <role> <issue> --new creates the next sequence file and switches current to it.
• artifact create performs the same selection or creation logic without launching the runtime.

Behavior

• Prompt composition order is fixed: core -> role -> templates -> issue context.
• Generated instruction files are written to .wingman/generated/ by default.
• Runtime launch is enabled by default. Use --no-launch for generation-only mode.
• mentor uses the issue spec template and asks for user decisions before finalizing a spec.
• issue create creates a GitHub Issue only when the user explicitly runs the command.
• issue create shows the target repository and asks for confirmation before writing to GitHub.
• issue create stops before GitHub access when Open Questions is not empty.
• wingman tracks managed artifacts in .wingman/artifacts.json.
• wingman mentor reuses the current pre-issue spec artifact by default and wingman mentor --new advances to the next spec artifact.
• <role> <issue> reuses the current artifact by default.
• <role> <issue> --new creates the next artifact file and switches current to it.
• issue create binds a managed mentor spec artifact back to the created issue number when possible.
• Wingman stores Codex session ids in the manifest and resumes them when the matching artifact is launched again.
• coder <issue> --post and mentor <issue> --post post a matching local note file as a GitHub Issue comment.
• --file can be used with --post to select an exact note file when multiple candidates exist.
• artifact create can be used to prepare or advance managed artifacts without launching the runtime, including pre-issue mentor specs.
• coder checks issue readiness before implementation and stops when required information is missing.
• teacher is intentionally not included.

Development

npm install
npm run typecheck
npm run build

Run built CLI:

node dist/cli/index.js mentor

Repository Structure

src/              # TypeScript source
wingman-prompts/  # Wingman prompt assets
dist/             # Build output