2026-02-21 03:10:39 +00:00
# Claude Code Instructions
## Task Master AI Instructions
**Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.**
@./.taskmaster/CLAUDE.md
2026-04-02 01:33:56 +01:00
## Skill routing
When the user's request matches an available skill, ALWAYS invoke it using the Skill
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
The skill has specialized workflows that produce better results than ad-hoc answers.
Key routing rules:
- Product ideas, "is this worth building", brainstorming → invoke office-hours
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
- Ship, deploy, push, create PR → invoke ship
- QA, test the site, find bugs → invoke qa
- Code review, check my diff → invoke review
- Update docs after shipping → invoke document-release
- Weekly retro → invoke retro
- Design system, brand → invoke design-consultation
- Visual audit, design polish → invoke design-review
- Architecture review → invoke plan-eng-review
- Save progress, checkpoint, resume → invoke checkpoint
- Code quality, health check → invoke health
feat(agents): smoke tests + README + docs (Stage 6, final)
Closes the agents feature.
Smoke tests (run via `pnpm test:smoke` against a live mcpd at
$MCPD_URL, default https://mcpctl.ad.itaz.eu):
* tests/smoke/agent.smoke.test.ts — full CRUD round-trip:
create secret + Llm + agent with sampling defaults; `get agents`
surfaces it; `get agent foo -o yaml | apply -f` round-trips
identically; create + list a thread via the HTTP API; agent delete
leaves Llm + secret intact (Restrict + SetNull as designed). Self-
skips with a warning when /healthz is unreachable.
* tests/smoke/agent-chat.smoke.test.ts — gated on
MCPCTL_SMOKE_LLM_URL + MCPCTL_SMOKE_LLM_KEY. Provisions secret +
Llm + agent against a real upstream, runs `mcpctl chat -m … --no-
stream` (asserts a reply lands), then runs the streaming default
(asserts text on stdout + `(thread: …)` on stderr). The fast path
for verifying the in-cluster qwen3-thinking deployment:
MCPCTL_SMOKE_LLM_URL=http://litellm.nvidia-nim.svc.cluster.local:4000/v1 \
MCPCTL_SMOKE_LLM_MODEL=qwen3-thinking \
MCPCTL_SMOKE_LLM_KEY=$(pulumi config get --stack homelab \
secrets:litellmMcpctlGatewayToken) \
pnpm test:smoke
Docs:
* README.md — new "Agents" section under Resources with the
qwen3-thinking quickstart and links to docs/agents.md and
docs/chat.md. Adds llm + agent rows to the resources table.
* docs/agents.md (new) — full reference: data model, chat-parameter
table, HTTP API, RBAC mapping, tool-use loop semantics, yaml
round-trip shorthand, the kubernetes-deployment wiring recipe,
and a troubleshooting section (namespace collision, llm-in-use,
pending-row recovery, Anthropic-tool limitation).
* docs/chat.md (new) — user-facing `mcpctl chat` walkthrough:
modes, per-call flags, slash-commands, threads, and a
troubleshooting section.
* CLAUDE.md — adds a "Resource types" cheatsheet with one-line
pointers to each, including the new `agent` row that links to
the docs.
All suites still green: mcpd 759/759, mcplocal 715/715, cli 430/430.
Smoke tests typecheck and self-skip when no live mcpd is reachable.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 17:08:37 +01:00
## Resource types
`mcpctl` resource cheatsheet:
- `server` — MCP server definition
- `instance` — running container (immutable, replicas-managed)
- `secret` / `secretbackend` — credentials
- `template` — reusable server blueprint
- `project` — workspace grouping servers, prompts, agents
- `llm` — server-managed LLM provider (api key + endpoint)
- `agent` — LLM persona pinned to one Llm; project attach surfaces project Prompts as system context, project MCP servers as tools, and exposes the agent itself as an MCP virtual server (`agent-<name>/chat` ). See `docs/agents.md` , `docs/chat.md` .
docs(agentic-teams): document the new resources, and make the webhook reachable
Five resources shipped with no documentation and one documented lie:
docs/inference-tasks.md still told people `mcpctl get tasks` lists the
inference queue. Work items own that name now.
Adds docs/epics.md (the Epic -> EpicTask -> Task hierarchy, the state machine,
risk-scaled review gates, the accept-merges gate, and reconciliation),
docs/gitproviders.md (forge registration, discovery/import, merge-on-accept,
post-merge reopen) and docs/agent-authority.md (the three run modes, and
plainly which two are not implemented).
Two things found while writing them, both fixed rather than filed:
- `webhookSecretKey` was read by the webhook route but writable from NOWHERE
-- absent from the create schema, update schema, service, CLI and apply
spec. Since the endpoint fails closed on a null key, post-merge CI failures
could never reopen their task; the board would keep claiming `merged` for
work that broke the build. Adds --webhook-secret-key, the schema fields and
the apply key, with tests covering persist / omit / explicit-null /
reject-empty. Omission deliberately does not clear the column, so an
unrelated edit cannot silently disarm the webhook.
- src/cli/src/commands/create.ts contained a literal NUL byte inside a string
literal (a binary-file check written with the raw character rather than an escape). Identical behaviour, but it made the whole file read as
binary, so `grep -I` skipped it entirely and 1120 lines of CLI were
invisible to every text search. Replaced with the escape.
The Epic write path (criteria/status/tradeoffs) is API-only -- documented as
such rather than papered over, and filed as task 180.
Full suite 2612 green; lint at baseline 794/77.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4wNHWf7xSwnZCWpJcyv9p
2026-08-16 00:14:58 +01:00
Tool access is bounded by **whoever invoked the run ** , not by the agent's
memberships — knowledge travels, action is gated. See `docs/agent-authority.md` .
docs: skills + revisions + proposals reference, plus cheatsheet update
Phase 7 of the Skills + Revisions + Proposals work — documentation
pass for the surface added in PR-1 through PR-6. Reference material
only; no code changes.
## What's added
- `docs/skills.md` — skill model, scoping rules, CLI surface, the
`mcpctl config claude --project` setup flow, metadata schema (with
the deferred-execution note for hooks/mcpServers/postInstall), the
on-disk state file shape, atomic install mechanics, failure
semantics, and what's deferred.
- `docs/revisions.md` — ResourceRevision model, semver auto-bump
rules, contentHash diff key (cross-resource sync), CLI for history
/ diff / restore, RBAC, audit emission, storage growth note.
- `docs/proposals.md` — ResourceProposal model, the reviewer flow
(CLI + web UI), atomic-approval mechanics, the propose_prompt /
propose_skill MCP tools, the propose-learnings global skill that
steers Claude toward engaging with them, and the deferred legacy
PromptRequest cutover.
## What's edited
- Top-level `CLAUDE.md` — resource cheatsheet adds `skill`, `proposal`,
`revision` with cross-references to the new docs. The legacy
`promptrequest` entry stays (still on the legacy code path) but
notes that new work should use `proposal`.
## What's NOT in this PR
- The PromptRequest → ResourceProposal cutover migration. Both run
side-by-side today; the focused cutover PR will rename + backfill +
drop. Keeping that out of PR-7 means review can stay on docs.
- Bundle-backup / `mcpctl apply -f` skill support (deferred from PR-3).
- `metadata.hooks` / `metadata.mcpServers` / `metadata.postInstall`
execution (deferred from PR-5).
- Existing-page UI migration to Tailwind (deferred from PR-6 — old
inline-styled pages coexist fine inside the new Layout).
These are tracked as future PRs; each is its own focused change.
## Verification
`pnpm test:run` whole monorepo: 162 test files / 2157 tests green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 17:58:04 +01:00
- `prompt` / `promptrequest` — curated content / legacy pending proposal (use `proposal` for new work).
- `skill` — Claude Code skill bundle (SKILL.md + files + typed metadata). Materialised onto disk by `mcpctl skills sync` . See `docs/skills.md` .
- `proposal` — generic pending proposal queue, replaces `promptrequest` . Covers both prompts and skills. See `docs/proposals.md` . Triage via `mcpctl review` .
- `revision` — append-only audit + diff log shared by prompts and skills. Auto-bumps semver on save. See `docs/revisions.md` .
docs(agentic-teams): document the new resources, and make the webhook reachable
Five resources shipped with no documentation and one documented lie:
docs/inference-tasks.md still told people `mcpctl get tasks` lists the
inference queue. Work items own that name now.
Adds docs/epics.md (the Epic -> EpicTask -> Task hierarchy, the state machine,
risk-scaled review gates, the accept-merges gate, and reconciliation),
docs/gitproviders.md (forge registration, discovery/import, merge-on-accept,
post-merge reopen) and docs/agent-authority.md (the three run modes, and
plainly which two are not implemented).
Two things found while writing them, both fixed rather than filed:
- `webhookSecretKey` was read by the webhook route but writable from NOWHERE
-- absent from the create schema, update schema, service, CLI and apply
spec. Since the endpoint fails closed on a null key, post-merge CI failures
could never reopen their task; the board would keep claiming `merged` for
work that broke the build. Adds --webhook-secret-key, the schema fields and
the apply key, with tests covering persist / omit / explicit-null /
reject-empty. Omission deliberately does not clear the column, so an
unrelated edit cannot silently disarm the webhook.
- src/cli/src/commands/create.ts contained a literal NUL byte inside a string
literal (a binary-file check written with the raw character rather than an escape). Identical behaviour, but it made the whole file read as
binary, so `grep -I` skipped it entirely and 1120 lines of CLI were
invisible to every text search. Replaced with the escape.
The Epic write path (criteria/status/tradeoffs) is API-only -- documented as
such rather than papered over, and filed as task 180.
Full suite 2612 green; lint at baseline 794/77.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4wNHWf7xSwnZCWpJcyv9p
2026-08-16 00:14:58 +01:00
- `epic` / `epictask` / `task` — the work tracker: vision → roadmap node → work item.
Tasks carry a risk level that decides which review gates they must pass, and
accepting one **merges its PR ** . See `docs/epics.md` .
* * `tasks` = work items**; the inference queue is `inference-tasks` / `itasks` .
- `gitprovider` / `repo` — git forge connection + attached repositories. Discovery
and import via `mcpctl repos discover|import` ; a forge connection is what makes
merge-on-accept possible. See `docs/gitproviders.md` .
feat(agents): smoke tests + README + docs (Stage 6, final)
Closes the agents feature.
Smoke tests (run via `pnpm test:smoke` against a live mcpd at
$MCPD_URL, default https://mcpctl.ad.itaz.eu):
* tests/smoke/agent.smoke.test.ts — full CRUD round-trip:
create secret + Llm + agent with sampling defaults; `get agents`
surfaces it; `get agent foo -o yaml | apply -f` round-trips
identically; create + list a thread via the HTTP API; agent delete
leaves Llm + secret intact (Restrict + SetNull as designed). Self-
skips with a warning when /healthz is unreachable.
* tests/smoke/agent-chat.smoke.test.ts — gated on
MCPCTL_SMOKE_LLM_URL + MCPCTL_SMOKE_LLM_KEY. Provisions secret +
Llm + agent against a real upstream, runs `mcpctl chat -m … --no-
stream` (asserts a reply lands), then runs the streaming default
(asserts text on stdout + `(thread: …)` on stderr). The fast path
for verifying the in-cluster qwen3-thinking deployment:
MCPCTL_SMOKE_LLM_URL=http://litellm.nvidia-nim.svc.cluster.local:4000/v1 \
MCPCTL_SMOKE_LLM_MODEL=qwen3-thinking \
MCPCTL_SMOKE_LLM_KEY=$(pulumi config get --stack homelab \
secrets:litellmMcpctlGatewayToken) \
pnpm test:smoke
Docs:
* README.md — new "Agents" section under Resources with the
qwen3-thinking quickstart and links to docs/agents.md and
docs/chat.md. Adds llm + agent rows to the resources table.
* docs/agents.md (new) — full reference: data model, chat-parameter
table, HTTP API, RBAC mapping, tool-use loop semantics, yaml
round-trip shorthand, the kubernetes-deployment wiring recipe,
and a troubleshooting section (namespace collision, llm-in-use,
pending-row recovery, Anthropic-tool limitation).
* docs/chat.md (new) — user-facing `mcpctl chat` walkthrough:
modes, per-call flags, slash-commands, threads, and a
troubleshooting section.
* CLAUDE.md — adds a "Resource types" cheatsheet with one-line
pointers to each, including the new `agent` row that links to
the docs.
All suites still green: mcpd 759/759, mcplocal 715/715, cli 430/430.
Smoke tests typecheck and self-skip when no live mcpd is reachable.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 17:08:37 +01:00
- `rbac` — access control bindings
- `mcptoken` — bearer credentials for HTTP-mode mcplocal
