agent-workflow-kit
v0.7.0
Published
Scaffold AI agent team workflows for coding projects.
Maintainers
Readme
agent-workflow-kit
Scaffold AI agents workflow files into an existing coding project.
agent-workflow-kit installs the awkit CLI. The CLI copies bundled static templates from templates/default into the current working directory and uses a manifest to decide every generated target path.
Install
npm install -g agent-workflow-kitUse without a global install:
npx agent-workflow-kit initCommands
awkit --help
awkit --version
awkit init
awkit init --dry-run
awkit mcp
awkit mcp --dry-runawkit init scaffolds Claude Code and Codex workflow resources for multi-agent planning, implementation, review, skills, and commands.
awkit init --dry-run previews files that would be created, overwritten, or skipped without writing anything. Run it before initializing inside an existing project.
awkit mcp registers the bundled Jira MCP server into the project-local .mcp.json (merging with any existing server entries). See Jira MCP server below.
Scaffold Safety
Generated paths come from templates/default/manifest.json. Template source paths must end in .template, and generated target paths must be safe relative paths.
Existing files are never overwritten by default. When conflicts exist, the CLI prompts for a global choice or per-file decisions. Overwrite happens only when explicitly selected.
The CLI checks that the current working directory is writable before copying files.
Jira MCP server
agent-workflow-kit bundles a local, read-only MCP server (second bin: awkit-jira-mcp) that gives an MCP client (e.g. Claude Code) read access to Jira Server/Data Center tickets over stdio. It never creates, updates, comments on, or transitions anything in Jira.
Prerequisites
agent-workflow-kitinstalled in the project (npm install agent-workflow-kitor global/npx, same as Install).- A Jira Server/Data Center instance (Jira Cloud auth is not supported).
- A Jira Personal Access Token (PAT) for your account. In Jira: profile avatar → Personal Access Tokens → Create token. Copy it immediately — Jira won't show it again.
- An MCP client that reads
.mcp.json, such as Claude Code.
1. Register the server
From the project root:
awkit mcpThis writes (or merges into) a jira entry in the project's .mcp.json, preserving any other MCP servers already registered there. Preview the change first with:
awkit mcp --dry-run.mcp.json is typically committed to the repo, so this step never writes credentials into it — only the launch command.
2. Provide credentials
Set these before the server runs (it reads them from process.env at startup):
| Variable | Required | Meaning |
| --- | --- | --- |
| JIRA_BASE_URL | yes | Your Jira base URL, e.g. https://jira.yourcompany.com |
| JIRA_PAT | yes | The Personal Access Token from the prerequisites step. Sent as Authorization: Bearer <token> |
| JIRA_ATTACHMENT_MAX_BYTES | no | Attachment size limit in bytes. Default 10485760 (10 MB); larger attachments are skipped and reported as skipped |
Two ways to set them, in priority order (env vars win):
Environment variables — export them in your shell profile, or however your MCP client passes environment variables to spawned servers.
Local config file — create
jira-mcp.config.jsonin the project root:{ "baseUrl": "https://jira.yourcompany.com", "pat": "your-personal-access-token", "attachmentMaxBytes": 10485760 }
Either way, keep credentials out of version control — add jira-mcp.config.json to .gitignore if you use the file option.
3. Restart your MCP client
Claude Code (and most MCP clients) only pick up new .mcp.json entries on the next session/restart. Restart it, then confirm the jira server shows as connected (e.g. /mcp in Claude Code).
4. Use it
The server exposes exactly one tool: get_jira_ticket(input). input is either a ticket key or a full ticket URL:
get_jira_ticket("PROJ-123")
get_jira_ticket("https://jira.yourcompany.com/browse/PROJ-123")It returns the ticket's key, title, description, and comments as text, plus attachment content:
- text / markdown / JSON / CSV / source-code attachments — text extracted and inlined
- PDF and Office (
.docx/.xlsx/.pptx) attachments — text extracted (no embedded-doc images, no OCR) - standalone images — returned as image content blocks
- videos — reported as present but not processed
- oversized attachments (over
JIRA_ATTACHMENT_MAX_BYTES) — reported as skipped - very large results are truncated with a marker to stay within the MCP output budget
In practice, just ask your agent something like "pull the context for PROJ-123" or paste a ticket URL — the client calls the tool for you.
Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| Tool returns "not configured" | JIRA_BASE_URL/JIRA_PAT not set where the server process can see them | Set both env vars (or jira-mcp.config.json), then restart your MCP client |
| Tool returns "not authorized" (401/403) | PAT invalid, expired, or lacks permission on the ticket | Regenerate the PAT in Jira; confirm your account can view the ticket in the browser |
| Tool returns "not found" | Wrong key/URL, or no access to that project | Double-check the key; confirm the ticket exists and is visible to your account |
| Server doesn't show up in the MCP client | .mcp.json not registered yet, or client not restarted since registering | Run awkit mcp, then fully restart the MCP client |
Security notes
- Strictly read-only — no write/update/delete/comment/transition calls are ever made.
- The PAT is never included in tool output, error messages, or logs.
awkit mcpnever writes credentials into.mcp.json.
