{
  "markdown": "# Workflow Toolkit\n\n**Get up to speed in any codebase, any size.**\n\nA non-opinionated workflow plugin for [Claude Code](https://claude.ai/code) that keeps track of what you're working on and what you need to do next. Session journaling, local task tracking, GitHub issue sync, knowledge base generation, and a handful of lifecycle hooks — all backed by a local SQLite database. Nothing leaves your machine.\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://claude.ai/code)\n\nBuilt by [Doug Silkstone](https://contra.com/doug_silkstone)\n\n---\n\n> **A note on slash commands:** This README is full of examples like `/workflow-toolkit:task-create` and `/workflow-toolkit:journal-read`. You don't have to use them that way. In fact, **I'd recommend you don't** — at least not at first. Just talk to Claude in natural language. Say \"create a task for fixing the login bug\" or \"what did I work on yesterday?\" and the skills will fire automatically when they're relevant. The slash commands are there when you know exactly what you want. Natural language is there for everything else. The best part of this plugin is that you can extend it and make it your own — the skills are just starting points.\n\n---\n\n## The Problem\n\nYou drop into an unfamiliar codebase — maybe it's a monorepo with 200 packages, maybe it's a legacy app with zero documentation. You start exploring, fixing bugs, shipping features. A few sessions later you can't remember what you changed on Tuesday, which issue you were investigating, or what you decided to do next.\n\nClaude Code sessions are ephemeral. Context disappears when the terminal closes. There's no trail of what happened, no way to pick up where you left off, and no structure to keep things moving forward. Multiply that across a team and it gets messy fast.\n\n**Workflow Toolkit gives you that structure** — without imposing opinions about how you work. It sits in the background, records what's happening, and gives you tools to query it, act on it, and build on it.\n\n---\n\n## Why SQLite and Not Just Markdown?\n\nMarkdown files are great for reading. They're terrible for querying.\n\nWhen you need to answer \"what did I work on last week?\", \"which issues are still untriaged?\", or \"how many tool calls did that refactor take?\" — you need structured data. SQLite gives you that. You can filter tasks by priority, search journal entries by keyword, aggregate session stats, and join issues to tasks — all with simple queries.\n\nBut we still write markdown too. Every session summary, every task, every journal entry also gets a human-readable `.md` file. You get the best of both: queryable data for Claude, browsable files for you.\n\nThe database auto-initializes on your first session. One file at `.claude/journal/journal.db`. No server, no config, no dependencies beyond `sqlite3`.\n\n---\n\n## Quick Start\n\n### Install Claude Code\n\n```bash\n# Native installer (recommended — auto-updates, no Node.js required)\ncurl -fsSL https://claude.ai/install.sh | bash\n\n# Or via npm (requires Node.js 18+)\nnpm install -g @anthropic-ai/claude-code\n```\n\n### Install the Plugin\n\n```bash\n# From inside Claude Code\n/plugin marketplace add dougwithseismic/workflow-toolkit\n/plugin install workflow-toolkit@dougwithseismic\n```\n\nOr clone and load directly:\n\n```bash\ngit clone https://github.com/dougwithseismic/workflow-toolkit.git\nclaude --plugin-dir ./workflow-toolkit\n```\n\nThe database initializes automatically on your first session. No config files to edit, no setup steps.\n\n---\n\n## How to Wrangle a Codebase\n\nHere's the workflow. You land in a new project — could be 10 files, could be 10,000. Here's how to start making sense of it and writing consistent code that matches the existing patterns.\n\n### Step 1: Let It Journal\n\nJust start working. The hooks run silently in the background:\n\n```\nSession Summary: abc123\n\nStarted: 2026-03-05 14:00:00\nEnded:   2026-03-05 15:45:00\n\n| Metric          | Count |\n|-----------------|-------|\n| Prompts         | 47    |\n| Tool Uses       | 183   |\n| Subagents       | 3     |\n| Compactions     | 1     |\n| Journal Entries | 2     |\n\nTop Tools Used:\nEdit (52x)  Read (41x)  Bash (38x)  Grep (27x)  Glob (25x)\n```\n\nEvery session gets a timestamped markdown file at `.claude/journal/entries/`. Come back next week and run `/workflow-toolkit:journal-read last 5` — instant context on where you left off.\n\nCapture decisions as you make them:\n\n```\n> /workflow-toolkit:journal-write Decided to use repository pattern — matches existing UserRepository and OrderRepository\n```\n\n### Step 2: Distill What You Learn\n\nThis is where it gets powerful. As you explore the codebase, distill the patterns you find:\n\n```\n> /workflow-toolkit:distill-concept react-hooks\n```\n\nThis doesn't just describe what React hooks are — it searches *this specific codebase*, reads real files, and generates a structured knowledge base entry at `knowledge-base/react-hooks.md`:\n\n```markdown\n# React Hooks\n\n> Custom hooks for data fetching, authentication, and UI state management.\n\n## Key Locations\n\n| Path                              | Purpose                              |\n|-----------------------------------|--------------------------------------|\n| `packages/lib/hooks/`             | Shared utility hooks                 |\n| `packages/features/bookings/hooks/` | Domain-specific booking hooks      |\n| `apps/web/hooks/`                 | App-level hooks                      |\n\n## Patterns\n\n### Data Fetching Hook\n\nWhere: `packages/lib/hooks/useFetch.ts:14`\n\nHow it works:\nWraps tRPC queries with loading/error state...\n\nExample:\n// packages/lib/hooks/useFetch.ts:14\nexport function useFetch<T>(queryKey: string) { ... }\n\n## Conventions\n- All hooks prefixed with `use`\n- Domain hooks live in their feature package, not in shared lib\n- Never call hooks conditionally (enforced by eslint rule)\n\n## Gotchas\n- `useBookingForm` has a hidden dependency on `BookingContext` — will throw if used outside the provider\n```\n\nReal code. Real file paths. Real conventions from *this* project, not generic best practices you'd find in a blog post.\n\n**Do this for every major concept as you encounter it:**\n\n```\n> /workflow-toolkit:distill-concept api-routers\n> /workflow-toolkit:distill-concept database-schema\n> /workflow-toolkit:distill-concept auth-flow\n> /workflow-toolkit:distill-concept testing-patterns\n> /workflow-toolkit:distill-concept error-handling\n```\n\nWithin a day you've got a `knowledge-base/` folder that any team member (or Claude Code session) can reference to write code that *matches the existing patterns*. No more guessing how things are done in this project.\n\n### Step 3: Track What Needs Doing\n\nSync the issues from GitHub so you can see the full picture locally:\n\n```\n> /workflow-toolkit:issues-sync --full --diff\n\nSynced 47 issues (32 open, 15 closed)\n\nNew issues (3):\n  #891 WebSocket connection drops after idle timeout\n  #889 Dark mode toggle doesn't persist\n  #887 Add bulk export for analytics\n```\n\nTriage them without leaving the terminal:\n\n```\n> /workflow-toolkit:issues-triage 891 priority critical\n> /workflow-toolkit:issues-triage 891 pick\n> /workflow-toolkit:issues-triage 891 note Likely related to keep-alive config in nginx\n```\n\nCreate local tasks for your own work:\n\n```\n> /workflow-toolkit:task-create Fix login redirect loop --priority high --tags \"auth,bug\" --issue 456\n\nCreated task #7: Fix login redirect loop\n  Priority: high | Tags: auth, bug | Issue: #456\n  Folder: .claude/tasks/fix-login-redirect-loop/\n```\n\nMove them through the lifecycle:\n\n```\n> /workflow-toolkit:task-start 7\nStarted task #7: Fix login redirect loop (priority: high)\n\n> /workflow-toolkit:task-done 7 Root cause was missing session cookie on redirect\nCompleted task #7: Fix login redirect loop\nDuration: 1h 23m\n```\n\nSee what's active:\n\n```\n> /workflow-toolkit:task-list\n\nid  title                        status       priority  issue  created_at\n--  ---------------------------  -----------  --------  -----  -------------------\n 5  Add rate limiting to API     in-progress  medium    #412   2026-03-04 09:00:00\n 3  Write onboarding docs        todo         low              2026-03-03 11:00:00\n\n2 active tasks (1 in-progress, 1 todo)\n```\n\nEach task gets its own folder at `.claude/tasks/<slug>/TASK.md` for reproduction steps, working notes, or anything else you want to persist.\n\n### Step 4: Ship It\n\nCheck your work before pushing:\n\n```\n> /workflow-toolkit:contribution-check\n\n| Check         | Status | Notes                          |\n|---------------|--------|--------------------------------|\n| Diff size     | PASS   | 8 files, +187 -42 lines       |\n| Commit format | PASS   | fix: handle timezone edge case |\n| File naming   | PASS   |                                |\n| Code quality  | WARN   | 1 potential issue found        |\n| Lint          | PASS   |                                |\n| Type check    | PASS   |                                |\n| Tests         | WARN   | 2 files missing test coverage  |\n\nAction Items:\n- [ ] Add tests for src/utils/timezone.ts\n- [ ] Review nested conditional at src/handlers/booking.ts:142\n```\n\nAuto-detects your project's linter and type checker — works with ESLint, Biome, Prettier, tsc, pyright, whatever.\n\nDraft the PR:\n\n```\n> /workflow-toolkit:pr-prepare 456\n\nPR Ready for Review\n\nTitle: fix: resolve login redirect loop caused by missing session cookie\nBase: main <- fix/login-redirect-loop\n\nBody:\n## What does this PR do?\nFixes the infinite redirect loop on login by ensuring the session cookie\nis set before the redirect fires...\n\n---\n\nNext steps (requires your approval):\n1. Push branch: git push -u origin fix/login-redirect-loop\n2. Create PR: gh pr create --draft --title \"...\" --body \"...\"\n```\n\nIt **stops here**. Nothing gets pushed until you explicitly say \"go ahead.\" If the project has a `.github/PULL_REQUEST_TEMPLATE.md`, it uses that template automatically.\n\n### Step 5: Extend the Workflow\n\nBuild new skills and agents as you discover needs specific to the project:\n\n```\n> /workflow-toolkit:create-skill deploy-preview \"Deploy a preview branch to staging\"\n```\n\nThis scaffolds a properly structured `SKILL.md` with YAML frontmatter, argument handling, step-by-step instructions, and validation. It follows Claude Code's plugin conventions so the skill just works.\n\n```\n> /workflow-toolkit:create-agent security-scanner \"Scan code for OWASP top 10 vulnerabilities\"\n```\n\nAgents get their own model selection, tool permissions, and system prompts. The scaffolder walks you through the design decisions.\n\nNeed both? The factory creates coordinated pairs:\n\n```\n> /workflow-toolkit:skill-and-agent-factory both code-review \"Quick inline review + thorough isolated analysis\"\n```\n\nThis creates a skill for fast in-context checks and an agent for deep isolated analysis — wired together so the skill can delegate to the agent when you need the thorough version.\n\n---\n\n## GitHub Issue Tracking\n\nThis requires the [GitHub CLI](https://cli.github.com/) (`gh`). Install it and authenticate:\n\n```bash\n# macOS\nbrew install gh\n\n# Windows\nscoop install gh\n\n# Linux\nsudo apt install gh\n\n# Then authenticate\ngh auth login\n```\n\nOnce `gh` is set up, issues sync from whatever repo your current directory belongs to:\n\n```\n> /workflow-toolkit:issues-sync --full --diff\n```\n\n**This is strictly read-only.** The plugin pulls issue data down into your local database. It never posts comments, creates issues, modifies labels, or touches anything on GitHub. Your triage metadata (priority, status, notes) stays entirely local.\n\nThe `github-issues` agent can handle bulk operations:\n\n```\n> @github-issues Triage all new issues from the last sync. Categorize by severity and suggest priorities.\n```\n\nIt reads issue bodies, correlates them with files in the codebase using Grep and Glob, and presents a structured triage report.\n\n---\n\n## Architecture\n\n```\nClaude Code Lifecycle Events\n        |\n        v\n  Hooks (bash scripts)           <- silent, automatic\n        |\n        v\n  SQLite Database                <- .claude/journal/journal.db\n        |\n        v\n  Skills (query & act)           <- you invoke these\n  Markdown Files                 <- human-readable summaries\n```\n\n### What the Hooks Capture\n\n| Hook | Fires when | Records |\n|------|-----------|---------|\n| `SessionStart` | Session begins | Session ID, start time. Auto-creates DB if missing. |\n| `Stop` | Each response completes | Prompt count increment |\n| `PostToolUse` | Write/Edit/Bash used | Tool name, file path |\n| `SubagentStop` | Subagent finishes | Subagent count |\n| `PreCompact` | Context compaction | Compaction snapshot |\n| `TaskCompleted` | Background task done | Task summary as journal entry |\n| `SessionEnd` | Session closes | Full summary (SQLite + markdown file) |\n\n### Database Tables\n\nSix tables in one SQLite file:\n\n| Table | What it stores |\n|-------|---------------|\n| `sessions` | Per-session metrics (prompts, tool uses, subagents, compactions) |\n| `entries` | Journal entries — auto-generated and manual |\n| `tool_usage` | Every tool invocation with file paths |\n| `compaction_snapshots` | Context compaction events |\n| `github_issues` | Synced issues with local triage metadata (priority, status, notes) |\n| `tasks` | Local tasks with status, priority, tags, linked issues, timestamps |\n\nAll data lives at `$CLAUDE_PROJECT_DIR/.claude/journal/`. Per-project, local-only.\n\n---\n\n## All Skills\n\n| Skill | What it does |\n|-------|-------------|\n| `journal-write` | Write a manual journal entry |\n| `journal-read` | Query journal history (recent, search, by date) |\n| `task-create` | Create a task with priority, tags, linked issue |\n| `task-list` | List/filter tasks by status or priority |\n| `task-view` | Full task details with TASK.md notes |\n| `task-update` | Update any task field |\n| `task-start` | Mark a task as in-progress |\n| `task-done` | Mark a task as complete |\n| `issues-sync` | Sync GitHub issues into local DB |\n| `issues-list` | Filter/search synced issues |\n| `issues-view` | Full issue details with local metadata |\n| `issues-triage` | Set priority, status, or add notes |\n| `distill-concept` | Generate knowledge base entry from codebase patterns |\n| `contribution-check` | Pre-push validation checklist |\n| `pr-prepare` | Draft a PR and stop for review |\n| `create-skill` | Scaffold a new Claude Code skill |\n| `create-agent` | Scaffold a new Claude Code agent |\n| `skill-and-agent-factory` | Create coordinated skill + agent pairs |\n| `db-viewer` | Open the SQLite database in a GUI |\n\nAll invoked as `/workflow-toolkit:<skill-name>`.\n\n## Agents\n\n| Agent | Purpose |\n|-------|---------|\n| `contribution-guard` | Read-only code reviewer. Checks diffs against project rules. Never modifies anything. |\n| `github-issues` | Issue research, bulk triage, and codebase correlation via `gh` CLI. |\n\n---\n\n## Plugin Structure\n\n```\nworkflow-toolkit/\n├── .claude-plugin/\n│   └── plugin.json              # Plugin manifest\n├── skills/                      # 19 skills (each a folder with SKILL.md)\n├── agents/                      # 2 specialized agents\n│   ├── contribution-guard.md\n│   └── github-issues.md\n├── hooks/                       # 8 lifecycle hooks + config\n│   ├── hooks.json\n│   ├── init-journal-db.sh       # Full database schema\n│   ├── session-start-hook.sh\n│   ├── journal-hook.sh\n│   ├── session-end-hook.sh\n│   ├── pre-compact-hook.sh\n│   ├── tool-use-hook.sh\n│   ├── subagent-stop-hook.sh\n│   └── task-completed-hook.sh\n├── scripts/\n│   └── sync-issues.js           # GitHub issue sync engine (Node.js)\n└── README.md\n```\n\n---\n\n## Prerequisites\n\n| Dependency | What for | Install |\n|------------|----------|---------|\n| [Claude Code](https://claude.ai/code) | Everything | `curl -fsSL https://claude.ai/install.sh \\| bash` |\n| `sqlite3` | Hooks & skills | Most systems have it. `brew install sqlite3` / `scoop install sqlite3` |\n| `jq` | Hook JSON parsing | `brew install jq` / `scoop install jq` |\n| [`gh`](https://cli.github.com/) | GitHub issue sync (optional) | `brew install gh` / `scoop install gh` + `gh auth login` |\n\n---\n\n## Safety\n\n- **Never pushes code** or creates PRs without your explicit consent\n- **Never posts to GitHub** — issue sync is strictly read-only\n- **Never modifies files** during contribution checks — read and report only\n- **All data stays local** to the project directory\n- **No telemetry, no network calls** except `gh` CLI when you manually trigger an issue sync\n\n---\n\n## Contributing\n\nContributions welcome. Fork it, improve it, open a PR.\n\nIf you build something on top of this or extend it for your team's workflow, I'd love to hear about it.\n\n---\n\n## License\n\nApache 2.0\n\n---\n\nBuilt by [Doug Silkstone](https://contra.com/doug_silkstone)\n",
  "bytes": 16786,
  "sha": "ace09e01dfa858be838dfb8d75ee770ea8e5a187ad282043458ad354cdbb43b4",
  "repo_slug": "dougwithseismic/workflow-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dougwithseismic_workflow_toolkit_workflo_41ae460a/readme"
}