@softspark/ai-toolkit 2.1.2 → 2.2.0

package/AGENTS.md

@@ -386,28 +386,291 @@ Testing expert. Use for writing tests (unit, integration, e2e), TDD workflow, te
 
 ---
 
-<!-- TOOLKIT:jira-rules START -->
+<!-- TOOLKIT:ai-toolkit START -->
+<!-- Auto-generated by ai-toolkit. Re-run to update. -->
+
+# AI Toolkit — Codex CLI Configuration
+
+Shared AI development toolkit with specialized agents, Codex-compatible skills, quality hooks, and a safety constitution.
+
+## Available Agents
+
+Specialized agent personas — apply their expertise for relevant tasks:
+
+- **ai-engineer**: AI/ML integration specialist. Use for LLM integration, vector databases, RAG pipelines, embeddings, AI agent orchestration, document indexing, semantic search, hybrid retrieval, and answer generation. Triggers: ai, ml, llm, embedding, vector, rag, agent, openai, anthropic, search, retrieval, indexing, chunking, reranking.
+- **backend-specialist**: Expert backend architect for Node.js, Python, PHP, and modern serverless systems. Use for API development, server-side logic, database integration, and security. Triggers: backend, server, api, endpoint, database, auth, fastapi, express, laravel.
+- **business-intelligence**: Opportunity Discovery agent. Scans data models and code to identify missing business metrics, KPIs, and opportunities for value creation.
+- **chaos-monkey**: Resilience testing agent. Use to inject faults, latency, and failures into the system to verify robustness and recovery mechanisms.
+- **chief-of-staff**: Executive Summary agent. Aggregates reports from all other agents to reduce noise and present a single, actionable daily briefing to the user.
+- **code-archaeologist**: Legacy code investigation and understanding specialist. Trigger words: legacy code, code archaeology, dead code, technical debt, dependency analysis, refactoring, code history
+- **code-reviewer**: Code review and security audit expert. Use for security reviews, Devil's Advocate analysis, quality audits, best practices validation. Triggers: review, security, audit, quality, best practices, vulnerability.
+- **command-expert**: CLI commands and shell scripting specialist. Trigger words: bash, shell, CLI, script, automation, command line, build script, deployment script
+- **data-analyst**: Data analysis and visualization expert. Use for SQL queries, data exploration, analytics, reporting, and insights. Triggers: data, analysis, sql, query, visualization, metrics, dashboard, pandas, report.
+- **data-scientist**: Statistical analysis and data insights specialist. Use for statistical analysis, data visualization, EDA, A/B testing, and predictive modeling. Triggers: statistics, visualization, eda, analysis, hypothesis testing, ab test.
+- **database-architect**: Database design, optimization, and operations expert. Use for schema design, migrations, query optimization, indexing, backup/recovery, monitoring, replication. Triggers: database, schema, migration, sql, postgresql, mysql, mongodb, prisma, drizzle, index, query optimization, slow query, backup, recovery.
+- **debugger**: Root cause analysis expert. Use for cryptic errors, stack traces, intermittent failures, silent bugs, and systematic debugging. Triggers: debug, error, exception, traceback, bug, failure, root cause.
+- **devops-implementer**: Infrastructure implementation expert. Use for writing Terraform, Ansible, Docker, and shell scripts based on approved architecture notes and implementation summaries. Triggers: terraform, ansible, docker, kubernetes, shell, infrastructure, deployment, configuration.
+- **documenter**: Documentation and KB expert. Use for architecture notes, runbooks, changelogs, KB updates, how-to guides, API docs, READMEs, tutorials, SOP creation, KB organization, content quality review. Triggers: document, documentation, architecture-note, runbook, changelog, howto, readme, kb, sop, technical writing.
+- **explorer-agent**: Codebase exploration and discovery agent. Use for mapping project structure, finding dependencies, understanding architecture, and research. Does NOT write code - only reads and analyzes.
+- **fact-checker**: Claim verification expert. Use for verifying facts, source validation, RAG result accuracy checking. Triggers: fact check, verify, accuracy, claim, source validation.
+- **frontend-specialist**: Senior Frontend Architect for React, Next.js, Vue, and modern web systems. Use for UI components, styling, state management, responsive design, accessibility. Triggers: component, react, vue, ui, ux, css, tailwind, responsive, nextjs.
+- **game-developer**: Game development across all platforms (PC, Web, Mobile, VR/AR). Use for Unity, Godot, Unreal, Phaser, Three.js. Covers game mechanics, multiplayer, optimization, 2D/3D graphics.
+- **incident-responder**: Production incident response expert. Use for P1-P4 incidents, outages, emergency fixes, and postmortem documentation. Triggers: incident, outage, production down, emergency, P1, alert, monitoring.
+- **infrastructure-architect**: System design expert. Use for architectural decisions, architecture notes, trade-off analysis, technology selection. Triggers: architecture, design, decision, trade-off, scalability, infrastructure planning.
+- **infrastructure-validator**: Deployment validation expert. Use for deployment verification, health checks, testing, rollback procedures. Triggers: validate, deploy, deployment, health check, smoke test, rollback.
+- **llm-ops-engineer**: LLM operations expert. Use for LLM caching, fallback strategies, cost optimization, observability, and reliability. Triggers: llm, language model, openai, ollama, caching, fallback, token, cost.
+- **mcp-specialist**: MCP server design, implementation, client configuration, and integration troubleshooting. Triggers: mcp, model context protocol, json-rpc, sse, stdio, mcp server, mcp config, mcp integration, mcp connection, claude desktop, mcp client.
+- **mcp-testing-engineer**: MCP protocol testing expert. Use for MCP server testing, protocol compliance, transport validation, integration testing. Triggers: mcp test, protocol compliance, mcp validation, transport testing.
+- **meta-architect**: Self-Optimization agent. Analyzes system performance and mistakes to update agent definitions and instructions. The only agent allowed to modify .claude/agents/*.
+- **ml-engineer**: Machine learning systems specialist. Use for model training, data pipelines, MLOps, and model deployment. Triggers: ml, machine learning, model training, mlops, tensorflow, pytorch, scikit-learn.
+- **mobile-developer**: Expert in React Native, Flutter, and native mobile development. Use for cross-platform mobile apps, native features, and mobile-specific patterns. Triggers: mobile, react native, flutter, ios, android, app store, expo, swift, kotlin.
+- **night-watchman**: Autonomous maintenance agent. Use for automated dependency updates, dead code removal, refactoring, and project hygiene tasks. Typically scheduled to run off-hours.
+- **nlp-engineer**: Natural Language Processing specialist. Use for text processing, NER, text classification, information extraction, and language model fine-tuning. Triggers: nlp, ner, tokenization, text classification, sentiment, spacy, transformers.
+- **orchestrator**: Multi-agent coordination and task orchestration. Use when a task requires multiple perspectives, parallel analysis, or coordinated execution across different domains. Invoke for complex tasks benefiting from security, backend, frontend, testing, and DevOps expertise combined.
+- **performance-optimizer**: Performance optimization expert. Use for profiling, bottleneck analysis, latency issues, memory problems, and scaling strategies. Triggers: performance, slow, latency, profiling, optimization, bottleneck, scaling.
+- **predictive-analyst**: Precognition agent. Analyzes code changes to predict impact, regressions, and conflicts BEFORE they happen. Uses dependency graphs and historical data.
+- **product-manager**: Product management and value maximization expert. Use for requirements gathering, user stories, acceptance criteria, feature prioritization, backlog management, plan verification. Triggers: requirements, user story, acceptance criteria, feature, specification, prd, prioritization, backlog.
+- **project-planner**: Smart project planning agent. Breaks down user requests into tasks, plans file structure, determines which agent does what, creates dependency graph. Use when starting new projects or planning major features.
+- **prompt-engineer**: LLM prompt design and optimization specialist. Trigger words: prompt, LLM, chain-of-thought, few-shot, system prompt, prompt engineering, token optimization
+- **qa-automation-engineer**: Test automation and QA specialist. Use for E2E testing, API testing, performance testing, and CI/CD test integration. Triggers: e2e, playwright, cypress, selenium, api test, performance test, automation.
+- **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
+- **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
+- **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
+- **seo-specialist**: Search engine optimization specialist. Trigger words: SEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org
+- **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
+- **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
+- **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
+- **test-engineer**: Testing expert. Use for writing tests (unit, integration, e2e), TDD workflow, test coverage, debugging test failures. Triggers: test, pytest, unittest, coverage, tdd, testing, mock, fixture.
+
+## Available Skills
+
+Skills are invocable commands or auto-loaded knowledge sources:
+
+- **agent-creator**: Creates new specialized agents with frontmatter, tool selection, and delegation guidance
+- **analyze**: Analyze code quality, complexity, and patterns
+- **api-patterns**: Loaded when user asks about REST API design or GraphQL patterns
+- **app-builder**: Loaded when user asks to scaffold or build a full-stack app
+- **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling. Codex-adapted: uses native subagents and plan tracking.
+- **architecture-decision**: Loaded when user asks about architecture decisions or architecture note writing
+- **biz-scan**: Scan codebase for business opportunities and KPIs
+- **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
+- **briefing**: Generate executive daily briefing across all agents
+- **build**: Build the project with auto-detected toolchain
+- **chaos**: Inject controlled faults for resilience testing
+- **ci**: Detect and run CI pipeline with status reporting
+- **ci-cd-patterns**: Loaded when user asks about CI/CD pipelines or deployment automation
+- **clean-code**: Loaded when user asks about clean code, naming, or code quality
+- **command-creator**: Creates new Claude Code slash commands with frontmatter, workflow guidance, and validation
+- **commit**: Create Conventional Commits with pre-commit validation
+- **council**: 4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'. Codex-adapted: uses native subagents and plan tracking.
+- **csharp-patterns**: Loaded when user asks about C# or .NET development patterns
+- **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
+- **database-patterns**: Loaded when user asks about database schema or query optimization
+- **debug**: Debug errors and trace root causes systematically
+- **debugging-tactics**: Loaded when user is debugging an issue or needs root cause analysis
+- **deploy**: Deploy with pre-flight checks and health verification
+- **design-an-interface**: Generate multiple radically different interface designs using parallel sub-agents, then compare on simplicity, depth, and correctness. Based on 'Design It Twice' from Ousterhout. Use when user wants to design an API, explore interface options, compare module shapes, or mentions 'design it twice'. Codex-adapted: uses native subagents and plan tracking.
+- **design-engineering**: Loaded when user asks about UI animations or CSS design craft
+- **docker-devops**: Loaded when user asks about Docker, containers, or DevOps patterns
+- **docs**: Generate and update README, API docs, and architecture notes
+- **documentation-standards**: Loaded when creating or updating KB documents, architecture notes, SOPs, or any file in kb/ directory
+- **ecommerce-patterns**: Loaded when user asks about e-commerce or shopping cart features
+- **evaluate**: Evaluate skill quality and RAG retrieval accuracy
+- **evolve**: Evolve agent definitions via meta-architect
+- **explain**: Explain code, architecture, or concepts with diagrams
+- **explore**: Explore codebase structure, stack, and architecture
+- **fix**: Auto-fix lint errors, type issues, and simple bugs
+- **flutter-patterns**: Loaded when user asks about Flutter or Dart development patterns
+- **git-mastery**: Loaded when user asks about advanced Git workflows or history rewriting
+- **grill-me**: Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'. Codex-adapted: uses native subagents and plan tracking.
+- **health**: Report service and infrastructure health status
+- **hipaa-validate**: Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references
+- **hive-mind**: Loaded when orchestrating multi-agent swarms or consensus workflows
+- **hook-creator**: Creates new Claude Code hooks with guided workflow, strict conventions, and validation
+- **index**: Index codebase into the knowledge base
+- **instinct-review**: Review and manage learned instincts from past sessions
+- **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
+- **java-patterns**: Loaded when user asks about Java development patterns
+- **kotlin-patterns**: Loaded when user asks about Kotlin development patterns
+- **lint**: Lint code with auto-detected tools and fix suggestions
+- **mcp-patterns**: Loaded when user asks about MCP servers or tool protocol design
+- **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
+- **migrate**: Run database migrations with backup verification
+- **migration-patterns**: Loaded when user asks about database migrations or zero-downtime deploys
+- **night-watch**: Run autonomous maintenance and dependency updates
+- **observability-patterns**: Loaded when user asks about logging, metrics, or tracing patterns
+- **onboard**: Generate project onboarding materials
+- **orchestrate**: Coordinate multiple specialized agents in parallel Codex-adapted: uses native subagents and plan tracking.
+- **panic**: Emergency stabilization via system-governor agent
+- **performance-profiling**: Loaded when user asks about performance profiling or optimization
+- **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
+- **plan**: Plan implementation with tasks and success criteria
+- **plan-writing**: Loaded when user asks to write an implementation plan or pre-mortem
+- **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
+- **pr**: Create pull requests with pre-flight validation
+- **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
+- **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets. Codex-adapted: uses native subagents and plan tracking.
+- **predict**: Predict regressions and impact before changes land
+- **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session. Codex-adapted: uses native subagents and plan tracking.
+- **rag-patterns**: Loaded when user asks about RAG systems, embeddings, or vector search
+- **refactor**: Refactor code for quality and maintainability
+- **refactor-plan**: Create a detailed refactor plan with tiny commits via user interview, then file as a GitHub issue RFC. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps. Codex-adapted: uses native subagents and plan tracking.
+- **repeat**: Run a prompt or slash command on a recurring interval until task complete or limits reached. Use when user wants to set up a recurring task, poll for status, or run something repeatedly on an interval. Codex-adapted: uses native subagents and plan tracking.
+- **research-mastery**: Loaded when user asks to research, verify, or synthesize information
+- **review**: Review code for quality, security, and correctness
+- **rollback**: Roll back a deployment safely with verification
+- **ruby-patterns**: Loaded when user asks about Ruby development patterns
+- **rust-patterns**: Loaded when user asks about Rust development patterns
+- **search**: Search the knowledge base with semantic and hybrid modes
+- **security-patterns**: Loaded when user asks about security, OWASP, or auth patterns
+- **skill-audit**: Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions
+- **skill-creator**: Create new skills from templates with guided workflow
+- **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks. Codex-adapted: uses native subagents and plan tracking.
+- **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms Codex-adapted: uses native subagents and plan tracking.
+- **swift-patterns**: Loaded when user asks about Swift or iOS development patterns
+- **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation. Codex-adapted: uses native subagents and plan tracking.
+- **teams**: Launch pre-configured Agent Teams for common workflows Codex-adapted: uses native subagents and plan tracking.
+- **test**: Run tests with coverage analysis and reporting
+- **testing-patterns**: Loaded when user asks about testing strategy, fixtures, or mocking
+- **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan. Codex-adapted: uses native subagents and plan tracking.
+- **typescript-patterns**: Loaded when user asks about TypeScript patterns or type safety
+- **ubiquitous-language**: Extract a DDD-style ubiquitous language glossary from the conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, or mentions DDD or domain model.
+- **verification-before-completion**: Loaded when agent is about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before assertions, always.
+- **workflow**: Start and manage autonomous agent workflows Codex-adapted: uses native subagents and plan tracking.
+- **write-a-prd**: Create a Product Requirements Document through interactive interview, codebase exploration, and deep module design. Use when user wants to write a PRD, create product requirements, or plan a new feature from scratch. Codex-adapted: uses native subagents and plan tracking.
+
+## Quality Standards
+
+Derived from the immutable safety constitution (5 articles):
+
+**Article I — Safety First**
+- No data loss: never delete files without backup verification or using reversible operations
+- No blind execution: never run LLM-generated code without static analysis or review
+- No infinite loops: all autonomous loops must have a maximum iteration count (max 3)
+
+**Article II — Hierarchy of Truth**
+- The Knowledge Base (`kb/`) is the source of truth; if code contradicts KB, check KB freshness
+- Use the research-mastery skill before any major decision; guessing is forbidden
+
+**Article III — Operational Integrity**
+- "Green Tests" is the only definition of Done; forced merges on red tests are unacceptable
+- Never delete audit logs or KB archives without explicit user approval and backup verification
+- Agents cannot change their own model or tool permissions without user approval
+
+**Article IV — Self-Preservation**
+- The constitution file is read-only for all agents except the user
+- If a constitutional violation is detected, halt the offending operation immediately
+
+**Article V — Resource Governance**
+- Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit user confirmation
+- Operate within assigned model tiers; model tier changes require user approval
+
+## Workflow Guidelines
+
+- **Plan First**: Tasks longer than 1 hour require a plan, success criteria, and pre-mortem
+- **Multi-Agent**: Use minimum 3 agents for complex tasks; single-agent for simple tasks
+- **2-Phase Execution**: Plan → User Approval → Implement (never skip the approval checkpoint)
+- **KB-First Research**: Search the knowledge base before writing code or answering questions
+- **Structured Commits**: Use `feat/fix/docs/refactor/test/chore` prefixes (Conventional Commits)
+- **Quality Gates**: Run `ruff check .` (Python), `tsc` (TypeScript), `go vet` (Go) before marking done
+- **Cite Sources**: Always reference `[PATH: ...]` when making decisions based on existing knowledge
+- **Read-Only Exploration**: Discovery agents never write; writing agents never explore blindly
+- **No Secrets in Code**: Never commit credentials, API keys, or sensitive configuration values
+<!-- TOOLKIT:ai-toolkit END -->
+
+<!-- TOOLKIT:jira-mcp START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->
 
 # Jira MCP Server
 
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `log_task_time`, `get_task_time_tracking`
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
 
 ## Key Rules
 
-- **Always `sync_tasks` first** before reading — cache may be stale.
-- **Time format:** `"2h 30m"` — hours and minutes only, never days.
+- **Always `sync_tasks` first** before reading -- cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English — always check first.
+- **Time format:** `"2h 30m"` -- hours and minutes only, never days.
 - **Status changes:** call `get_task_statuses` first to check valid transitions.
 - **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
+- **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
 
 ## Workflow
 
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` — fetch fresh
-2. `read_cached_tasks()` — work offline
-3. `get_task_details(task_key="PROJ-123")` — deep dive
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` — mutate
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` -- fetch fresh
+2. `read_cached_tasks()` -- work offline
+3. `get_task_details(task_key="PROJ-123")` -- deep dive (description + comments as markdown)
+4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` -- mutate
+
+## Comment Templates (8 built-in)
+
+| ID | Use for |
+|----|---------|
+| `status-update` | Progress report with completed/next/blockers |
+| `blocker-notification` | Escalate blocking issue |
+| `handoff-transition` | Task handoff between people |
+| `review-request` | Request code review |
+| `sprint-update` | Sprint progress report |
+| `bug-report` | Structured bug report |
+| `deployment-note` | Deployment documentation |
+| `time-log-summary` | Time logging with description |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `jira-mcp config init` | Initialize global config (~/.softspark/jira-mcp/) |
+| `jira-mcp config add-project <key> <url>` | Add Jira project mapping |
+| `jira-mcp config remove-project <key>` | Remove a project |
+| `jira-mcp config list-projects` | Show configured projects with language |
+| `jira-mcp config set-default <key>` | Set default project |
+| `jira-mcp config set-credentials` | Set API credentials |
+| `jira-mcp config set-language <lang>` | Set global default language |
+| `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
+| `jira-mcp create <path>` | Create tasks from template (dry-run default) |
+| `jira-mcp create-monthly` | Create monthly admin tasks |
+| `jira-mcp cache sync-users` | Cache user list for reassignment |
+| `jira-mcp cache sync-workflows` | Cache status transitions |
+| `jira-mcp cache list-users` | Show cached users |
+| `jira-mcp cache list-workflows` | Show cached workflows |
+
+## Architecture
+
+Four layers -- each depends only on layers below:
+
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
+
+## Coding Conventions
+
+- **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
+- **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
+- **Error classes**: extend `JiraMcpError` with `code` property
+- **ADF round-trip**: `markdownToAdf()` for writes, `adfToMarkdown()` for reads -- NEVER throw
+- **InstancePool**: singleton, lazy connectors, dedup by URL
+- **Dual-write**: after Jira mutation, update local cache, return API result
+- **Dry-run default**: `--execute` required for destructive operations
+- **DI pattern**: handlers accept `deps?` parameter for testing
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR` -- no manual config, no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/` -- see SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+
+## Testing
+
+- **Vitest**: 70% coverage threshold, `vi.fn()` for mocks
+- **No real Jira API calls** in tests, use `tests/fixtures/mocks.ts`
+- **Filesystem tests**: `os.tmpdir()` + `mkdtemp()`, NEVER write to `~/.softspark/`
+- Quick pre-commit: `npm run typecheck && npm run lint && npm test && npm run build`
+
+## KB & SOPs
+
+- `kb/reference/` -- architecture, api, configuration, adf, caching, templates
+- `kb/howto/` -- setup, multi-instance, cli-usage
+- `kb/procedures/` -- sop-pre-commit, sop-release, sop-post-release-testing
+
+<!-- TOOLKIT:jira-mcp END -->
 
-<!-- TOOLKIT:jira-rules END -->
 <!-- TOOLKIT:rag-mcp-rules START -->
 <!-- Auto-injected by ai-toolkit. Re-run to update. -->
 
@@ -432,4 +695,3 @@ Default tool: `smart_query()`. Use `hybrid_search_kb()` for speed, `crag_search(
 ALWAYS check `kb/procedures/` first: `smart_query("SOP for <task>")`.
 
 <!-- TOOLKIT:rag-mcp-rules END -->
-

package/CHANGELOG.md

@@ -7,10 +7,25 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## v2.1.2 — Idempotent Update Fix (2026-04-13)
+## v2.2.0 — URL Rules & Registry Safety (2026-04-14)
+
+### Added
+- **URL rule registration** — `ai-toolkit add-rule https://...` registers rules from HTTPS URLs. URL-sourced rules are tracked in `rules/sources.json` and auto-refreshed on every `ai-toolkit update`. Falls back to cached local copy on network failure.
+- **Version consistency validation** — `validate.py --strict` now cross-checks `package.json`, `manifest.json`, and `plugin.json` versions match
+
+### Fixed
+- **Project registry race condition** — parallel `install --local` during `ai-toolkit update` could silently drop registry entries. Fixed with `fcntl.flock` exclusive lock, atomic writes (tempfile + rename), and deferred sequential registration after parallel phase.
+- **Version drift** — `manifest.json` and `plugin.json` were stuck at 1.9.0 since v2.0.0, now synced
+- **Language rules count** — ARCHITECTURE.md claimed 70 files, actual is 68
+- **Skills catalog tiers** — added missing Tier 1.5 (planning pipeline + design/architecture)
+
+---
+
+## v2.1.3 — Idempotent Update Fix (2026-04-13)
 
 ### Fixed
-- **`ai-toolkit update` no longer dirties git** — generators now skip custom rule emission when called by `inject_with_rules()` (which handles injection separately). Previously, `update` caused AGENTS.md and other generated files to gain extra blank lines on every run.
+- **`ai-toolkit update` no longer dirties git** — `inject_with_rules()` now strips all existing TOOLKIT sections before re-injecting, and `generate_agents_md.py` includes the Codex block for format consistency. Running `update` on a clean repo leaves zero uncommitted changes.
+- **Custom rules always present** — all generators (standalone and via `inject_with_rules`) emit registered custom rules in every output format
 
 ---
 

package/README.md

@@ -6,11 +6,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-598%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-604%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.1.2
+## What's New in v2.1.3
 
 - **Idempotent update** — `ai-toolkit update` no longer dirties git with extra blank lines in generated files
 - **Custom rules in generators** — `generate:all` preserves registered rules from other repos across all platforms
@@ -142,7 +142,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (598 tests)
+├── tests/               # Bats test suite (604 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.9.0",
+  "version": "2.2.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -304,7 +304,7 @@ Lead Session (You)
 ### MCP Templates (25)
 `app/plugins/mcp-templates/` ships 25 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
-### Language Rules (70 files, 13 languages)
+### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.

package/bin/ai-toolkit.js

@@ -63,7 +63,7 @@ const COMMANDS = {
   status: 'Show installed modules, version, and profile from state.json',
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
-  'add-rule': 'Register a rule file in ~/.softspark/ai-toolkit/rules/ (applied on every install/update)',
+  'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
   'inject-hook': 'Inject external hooks into ~/.claude/settings.json (tagged with _source for idempotent updates)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json',
@@ -232,8 +232,8 @@ function showHelp() {
   console.log('  <source-name>   Source tag to remove (derived from hooks filename stem)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
-  console.log('  <rule-file>     Path to .md rule file to register globally');
-  console.log('  [rule-name]     Override rule name (default: filename without .md)');
+  console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
+  console.log('  [rule-name]     Override rule name (default: filename/URL stem without .md)');
   console.log('\nOptions for plugin:');
   console.log('  install <name>  Install a plugin pack (--editor claude|codex|all)');
   console.log('  install --all   Install all available plugin packs for selected editor(s)');
@@ -333,16 +333,18 @@ function handleRemoveRule(args) {
 }
 
 /**
- * Handle `ai-toolkit add-rule` -- validates rule file, resolves absolute path.
+ * Handle `ai-toolkit add-rule` -- validates rule file/URL, resolves absolute path.
  * @param {string[]} args
  */
 function handleAddRule(args) {
   const ruleFile = args[0];
   if (!ruleFile) {
-    console.error('Usage: ai-toolkit add-rule <rule-file> [rule-name]');
+    console.error('Usage: ai-toolkit add-rule <rule-file-or-url> [rule-name]');
     process.exit(1);
   }
-  const absRuleFile = path.resolve(CWD, ruleFile);
+  // Pass URLs through directly (don't resolve as filesystem path)
+  const isUrl = ruleFile.startsWith('https://') || ruleFile.startsWith('http://');
+  const absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);
 }

package/kb/procedures/maintenance-sop.md

@@ -319,6 +319,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 

package/kb/procedures/release-preparation-sop.md

@@ -108,8 +108,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 

package/kb/reference/skills-catalog.md

@@ -17,7 +17,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/llms-full.txt

@@ -3441,6 +3441,7 @@ Follow this sequence before every `npm publish` / `git tag`:
 
 ```bash
 # Edit package.json version field (semver: X.Y.Z)
+# Sync package-lock.json: npm install --package-lock-only
 # Add entry to CHANGELOG.md
 ```
 
@@ -3619,8 +3620,9 @@ The canonical version lives in `package.json`. These files **must** match:
 | `README.md` | Badge counts, "What You Get" table |
 | `app/ARCHITECTURE.md` | Section headings with counts |
 
-> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
-> count drift automatically. If tests pass, counts are correct.
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
 
 ### Verification command
 
@@ -8518,7 +8520,9 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 
 | Tier | Skills | When |
 |------|--------|------|
-| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, fast |
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/grill-me`, `/triage-issue` | One concern, fast |
+| **1.5 — Product planning** | `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues` | Interview-driven PRD → vertical-slice plan → GitHub issues |
+| **1.5 — Design & architecture** | `/design-an-interface`, `/architecture-audit`, `/refactor-plan`, `/ubiquitous-language`, `/qa-session` | Parallel sub-agent exploration |
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0",
+  "version": "2.2.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",