`jardis/dev-skills` — the process for Jardis projects

Version 1.7.1 · a Composer plugin that installs skills, an AGENTS.md process router and reviewer agent files into a Jardis project · five areas on this page: process map, knowledge cycle, skill map, installation picture, tool coverage

Fixed points:

33 bundled skills in nine areas, plus the skills of every Jardis vendor package
The profile core installs 25 of them; a Jardis package or profile jardis adds the other eight
Skills land in .claude/skills and .agents/skills; one managed block lands in AGENTS.md
Branch, commit and merge are gates of the human; no commit carries a tool attribution
19 reviewer roles (17 in the profile core) are written as agent files for five tools
Only Claude Code is tested; Codex, Cursor, GitHub Copilot and Gemini CLI are documented, not tested
The groups foundation-* and process-* are always installed
The switch process-docs keeps the process documents in the commit (committed) or out of it (local)

Human decides Reviewer (independent, fresh context) Artefact no role in this phase Skill name

Process map

Taskevery requestprocess-choose-tier

0 Answerquestion, explanation, typo

no process, answer directly

1 Single actionone thing, one place, no open decision

the main session does it itself · hygiene: update the docs, test changed logic, run only the gates the change touches, read the diff back

2 Small assignmentbig, loud or isolated or several subtasks

one sub-agent per subtask · the main session keeps the task list and verifies against ground truth, it does not implement · hygiene as in 1

3 Undertakingopen decision, dependent steps, new architecture, public API, data, security

stages below · when in doubt the lower tier · a tier-3 criterion that shows up decides for tier 3

▼

Phase

Conceptstage 0process-concept

PRDstage 1process-write-prd

Requirements boardon the PRD · once per undertakingprocess-review-board

Planstage 2process-write-plan

Design boardon the plan · once per undertakingprocess-review-board

Buildeach stage of the planprocess-run-stage

Verificationeach stage of the planprocess-verify

Acceptanceafter the last stageprocess-verify

Closeonce per undertakingprocess-close

Human decides

Interview: answers point by point · accepts the understanding sheet and the target picture (no yes, no next stage)

confirms the PRD

Every finding is ruled; every fork goes to the human, minor ones too

releases the plan

Every finding is ruled; every fork goes to the human

At most 2 question points per stage · commit and merge are gates of the human

Sight gate where a surface is built: target picture beside screenshot, always blocks

Accepts the gate verdict

Each open point gets one of four decisions · decides process changes from the retro

Reviewer

Before anything new: what the environment already does
existing-capability-check

—

Skeptic always, further roles only with a reason (domain, DDD strategy, frontend UX) · blind, in parallel · one merged list

—

Default two roles: architecture, test strategy · packages only for new package APIs · more only with a reason

Code review per phase (code-review-change) · open-question gate · failure diagnosis

Stage verifier, blind, once per stage, doer ≠ checker · QA gates once per stage by the main session

Acceptance gate, end to end against the whole PRD, once

—

Artefact

UNDERSTANDING.md · KONZEPT.html (+ KONZEPT.png at approval) · PROGRESS.md with head: Phase, Stage, Next step, Open decisions

PRD.md adds a solution part, error cases, states, limits, data paths and numbered decisions to the sheet and the picture

One finding list, every finding resolved or rejected

PLAN.md: stages → phases; per stage generated, by hand, done when, halt; file scope, acceptance criteria per phase

Findings worked into the plan

One brief per phase (≤ 6 KB, ≤ 8 commitments, ≤ 30 KB context load) · one commit per phase

Verdict GREEN or RED (≤ 5 items, ≤ 3 red proofs) · screenshot · merge

Per criterion MET or GAP · verdict GREEN or RED

Digest docs/digests/… · folder archived · delivery once

Stage loop

Per phase: brief → implementer (fresh session) → commit. Per stage: verifier → QA gates → sight gate → head update → merge. After RED: one fix run and one follow-up run of the verifier, then STOPP: in the progress head.

Failure path

A recoverable → one fresh retry · B answerable question → open-question gate (open-question-gate; the answer is derived from PRD, target picture, constitution and code) · diagnosis by failure-diagnosis · never delegated: destructive operations, public API changes, scope beyond the PRD, publication, cost, third parties

Knowledge

knowledge-* · read the pool before a format, architecture or emission decision · every feat: and fix: commit carries a Wissen: note line

Resume

process-resume · a fresh session finds the active PROGRESS.md (at most 60 lines, only the main session writes it), honours STOPP:, runs the preflight and takes up exactly one next step · every stage runs in a fresh agent session

Roles

Main session = orchestrator: writes briefs, watches, checks against ground truth, builds nothing · implementer = sub-agent per phase, writes no progress file and no state-changing git command · reviewer = own sub-agent that sees only the target artefact, the acceptance criteria and the code · without sub-agents: a fresh headless run per role (claude -p, codex exec, agent -p, copilot -p, gemini -p)

Source: the process router in AGENTS.md and the skills process-choose-tier, process-concept, process-write-prd, process-write-plan, process-review-board, process-run-stage, process-verify, process-close, process-resume.

Knowledge cycle

R read W write G Git hook or check D account (docs/)

Three layers: layer 1 chat (raw material, never the source of truth) → layer 2 project documents docs/vorhaben/<name>/ → layer 3 knowledge .claude/wissen/. The direction is fixed: chat, then project documents, then knowledge.

WHERE · knowledge pool (why and pitfalls)

.claude/wissen/INDEX.md is the entry point · one page per topic .claude/wissen/<topic>.md

StandEntscheideFallenErsetztVerweise

condensed, not appended · a decision carries date, author and source · page ≤ 16,384 bytes and 160 lines, index < 10,240 bytes

WHERE · account

docs/vorhaben/<name>/ holds PROGRESS, UNDERSTANDING, KONZEPT, PRD, PLAN
→ at close: docs/digests/digest-<name>-<yyyy-mm>.md, the folder is archived (moved to tmp/archiv/) before the delivery

WHERE · skills (what)

.claude/skills and .agents/skills arrive through Composer. The plugin writes the skills and never writes the pool; the agent creates the pool scaffold through process-concept.

IN THE REPO?

committed (default): everything is left to the commit
local (switch process-docs): the exclude block in .git/info/exclude also holds .claude/wissen/, docs/vorhaben/ and docs/digests/; .gitignore stays untouched

A · Project startno pool yet, first undertaking

WScaffold: empty INDEX.md, only when .claude/wissen/ is missing.claude/wissen/INDEX.md

WInterview: every settled point goes into the concept artefact, not into a chat summaryUNDERSTANDING.md · KONZEPT.html

DPRD, plan and progress file as the accountdocs/vorhaben/<name>/

RThe brief names the pool pages that touch the area, chosen from INDEX.mdINDEX.md → pages

WGA decision becomes one line in Entscheide; the feat: commit carries the noteWissen: <page>#<section>

RThe verifier receives the knowledge pages the briefs named

WDClose: triage · lessons into the pool · digest · folder archived · deliverydocs/digests/

Pool and docs committed · mode local: all of it under the exclude block, the digest too

B · Featuresingle action or undertaking

RBefore a format, architecture or emission decision, read the responsible pageINDEX.md → <topic>.md

Wfeat: extends Stand or Entscheide; a replaced fact moves to Ersetzt

WA page the change contradicts is corrected in the same commit

Gcommit-msg hook: a feat: or fix: commit without the note produces a warning, the commit goes throughWissen: <page>#<section> | Wissen: keins – <reason>

Gpool check: sections, links, path references and size capspool-check.php

The note stands in the Git history · pages committed or local

C · Bugfixwith or without an undertaking

WFix and a test for the changed logic

WPool entry only if all four criteria hold: not obvious from the code · regression · trap · pool wrong or incomplete

W2 to 4 lines in Fallen: symptom, cause, rule, source<topic>.md#Fallen

Gfix: carries Wissen: <page>#fallen or Wissen: keins – <reason>

WA wrong page is corrected in the same commit

as B

Checks

G pool-check.php only reads; exit code 0 clean, 1 violations, 2 usage error or no pool · the commit-msg hook only warns and always exits 0 · check-commit-messages <from>..<to> runs the same check over a commit range, for example in CI · install-commit-msg-hook writes the hook, git-setup-repository runs it

What the package puts in place for the cycle

Pool pointer in the router — the managed block in AGENTS.md carries the line “Wissenspool: .claude/wissen/INDEX.md — vor Entscheiden lesen, Vermerk-Pflicht”, so a session finds the pool without any private setting.

Tools shipped with the package — the commit-msg hook, its installer install-commit-msg-hook and the pool check pool-check.php come with jardis/dev-skills under scripts/.

Scaffold at the first undertaking — process-concept copies only INDEX.md into .claude/wissen/, and only when that folder is missing; an existing pool is never changed.

Offer at the end of a chat — a chat that produced more than an answer ends with two offers: create a project folder (docs/vorhaben/<name>/) and carry knowledge into the pool. The rule is in process-choose-tier; nothing is created without a yes.

PROGRESS.md with a fixed head — ## Kopf is the first heading, with four lines in this order: Phase, Stage, Next step, Open decisions. Five optional free lines may follow: Title, Type, Ticket, BC, Skipped.

Fresh session per stage — every stage, and every implementer session inside it, runs in a fresh agent session; the head of the progress file and the brief are the only hand-over. The rule is in process-run-stage.

Source: the skills knowledge-maintain-pool, knowledge-record-decision, process-concept, process-close, process-run-stage and the scripts under scripts/.

Skill map

Naming scheme: <area>-<what-it-does> · English · kebab-case

The area says where in the lifecycle a skill is used: start, packages, process, knowledge, git, design, generated-code, foundation; the review skill carries code-review. Skills of Jardis packages (adapter-*, core-*, support-*, tools-*) belong to those packages and are added on top.

start · packages entry

start-orientation

Entry point: walks the lifecycle phases and routes to every other skill

packages-find-existing

Before hand-building a reusable component, check which Jardis package already provides it, then composer require

process always installed · tier choice, stages 0 to 4, review

process-choose-tier

Decide how much process a task needs: answer, single action, small assignment or undertaking

process-check-existing

Before something new, ask what the environment already does, via a blind checker

process-concept

Stage 0: concept interview, understanding sheet, approved target picture, project folder with progress file

process-write-prd

Stage 1: the PRD adds a solution part, error cases, states, limits, data paths and numbered decisions; requirements board once

process-write-plan

Stage 2: cut into stages and phases with file scope, acceptance criteria and the lines generated, by hand, done when and halt; design board once

process-review-board

Choose roles with a reason, run them blind, merge one list, rule on every finding

process-run-stage

One brief per phase, a fresh implementer, commit, blind verification, QA gates, merge

process-verify

One blind verifier per stage and one end-to-end acceptance gate at the end

process-close

Triage open points, carry lessons into the pool, write the digest, archive the folder, deliver once (squash merge)

process-resume

Continue a running undertaking in a fresh session from its progress file

code-review-change

After every coding task and before any commit: findings graded Blocker, Major or Minor, never edits code

knowledge decision pool

knowledge-maintain-pool

Layout, size caps and upkeep of the pool under .claude/wissen/; the pool check

knowledge-record-decision

Record a decision or a bugfix lesson with date, author and source; the Wissen: note on feat: and fix: commits

git Gitflow

git-setup-repository

One-time Gitflow setup: develop branch, repository settings, branch ruleset, git hooks

git-start-branch

Create a Gitflow branch with issue number and type detection

git-commit-change

Conventional Commit from the current changes, after review

git-push-and-open-pr

Push with the quality gate and open a pull request

git-check-compliance

Check that the repository follows the Gitflow conventions

design before the generated code · profile jardis

design-draft-schema

Draft the content of a Schema.json for the Designer from a plain-text domain idea

design-headless-mcp

Drive a Jardis workspace without a browser through jardis mcp: tools, resources, error envelopes

generated-code after the Designer · profile jardis

generated-code-extend

Extend generated code: the hermetic generator-owned tree, the developer surface, the prohibitions

generated-code-wire-transport

Wire generated queries and processes into HTTP, CLI, queue or worker code

generated-code-versioning

ClassVersion resolution and the versioning model

generated-code-workflow-api

Workflow-engine API behind generated process orchestrators

generated-code-recipes

Recipes and troubleshooting for generated code

foundation standards, cross-cutting · always installed

foundation-architecture

Five pillars, hexagonal dependency direction, Closure-Orchestrator pattern

foundation-patterns

Catalogue of the ten design patterns used in Jardis

foundation-testing

Integration over unit, mock only at ports, a fixed process for failing tests

foundation-frontend-review

Stack-agnostic frontend review rules

foundation-php

PHP 8.3 reference: strict types, PHPStan level 8, PSR-4, no traits

foundation-working-principles

Skill first, then source code, then ask; verify values instead of guessing

Chains `prerequisites` / `next` from the skill frontmatter

Undertaking: process-choose-tier → process-concept → process-write-prd → process-write-plan → process-run-stage → process-verify → process-close → knowledge-record-decision

Other chains: git-start-branch → git-commit-change → git-push-and-open-pr · design-draft-schema → generated-code-extend → generated-code-* · foundation-working-principles → knowledge-maintain-pool → knowledge-record-decision · code-review-change → git-commit-change

Reviewer roles (sub-agent definitions in `process-review-board/reviewers/`)

Role	Used by	Taken when
`prd-review-skeptic`	requirements board	always
`prd-review-domain-expert`	requirements board	the PRD models a domain or a domain decision is open
`prd-review-ddd-strategy`	requirements board	contexts, domain language or a public API are cut or changed
`prd-review-frontend-ux`	requirements board	the PRD has a user interface
`plan-review-architecture`	design board	default
`plan-review-test-strategy`	design board	default
`plan-review-packages`	design board	the plan touches new package APIs
`plan-review-ddd-tactics`	design board	the plan cuts aggregates, value objects or repositories
`plan-review-php`	design board	the plan is mostly PHP code with error handling and edge cases that matter
`plan-review-frontend-architecture`	design board	the plan has a user interface
`plan-review-frontend-tests`	design board	the plan has a user interface
`plan-review-frontend-a11y`	design board	a phase produces an interface people operate
`plan-review-frontend-types`	design board	a phase touches types or data flow in the frontend
`plan-review-frontend-ux`	design board	the plan carries out interface states and interactions
`stage-verifier`	`process-verify`	once per stage
`acceptance-gate`	`process-verify`	once per undertaking, after the last stage
`existing-capability-check`	`process-check-existing`	before something new is introduced
`open-question-gate`	`process-run-stage`	before a question reaches the human
`failure-diagnosis`	`process-run-stage`	after RED, when the report does not explain the cause

Source: the frontmatter of the 33 skills under skills/ and docs/SKILL-FORMAT.md (area prefixes).

Installation picture in a Jardis project

# composer require --dev jardis/dev-skills  →  post-install / post-update
your-project/
├── AGENTS.md                         managed block BEGIN/END jardis/dev-skills
│     process router: tiers · phase → skill · reviewer roles · pointer to the pool
│     + aggregated AGENTS.md of the Jardis vendor packages   warning above 32,768 bytes (Codex)
├── CLAUDE.md                         managed block: imports @AGENTS.md
├── .claude/
│   ├── skills/<name>/SKILL.md          33 bundled skills (25 in the profile core) + vendor skills · Claude Code, Copilot
│   ├── skills/.jardis-managed.json     manifest: every skill folder the plugin installed
│   ├── agents/<role>.md                reviewer agent files (Claude Code)
│   └── .jardis-backup/                 copies of folders that differed from the managed state
├── .agents/skills/<name>/SKILL.md     the same skills for Codex, Cursor, Copilot, Gemini CLI
├── .codex/agents/<role>.toml          reviewer agent files (Codex)
├── .cursor/agents/<role>.md           reviewer agent files (Cursor)
├── .github/agents/<role>.agent.md     reviewer agent files (Copilot)
├── .gemini/agents/<role>.md           reviewer agent files (Gemini CLI)
├── .gemini/settings.json             context.fileName lists AGENTS.md
└── .git/info/exclude                 managed block: always .claude/.jardis-backup/; mode local adds more

# created later by the process, not by the install
├── .claude/wissen/                    knowledge pool · INDEX.md + topic pages · scaffold by process-concept
├── .claude/PROJECT_PROFILE.md          project facts: QA entry, ports, build · by process-concept
├── docs/vorhaben/<name>/             PROGRESS.md · UNDERSTANDING.md · KONZEPT.html/.png · PRD.md · PLAN.md · briefs
├── docs/digests/digest-<name>-<yyyy-mm>.md
└── commit-msg hook                    written by scripts/install-commit-msg-hook, warns only

Reviewers: one definition, thin files per tool

Layer	Content
Source (once)	The role text in `process-review-board/reviewers/<role>.md`. It is copied with the skill to `.claude/skills` and `.agents/skills`.
File per tool	One agent file per role and tool, written by the plugin. A file the plugin did not write is never overwritten; the plugin leaves it and warns.
Without sub-agents	The skill names the fallback: a fresh headless run per role with a pure review assignment.

Configuration `composer.json`

"extra": { "jardis/dev-skills": {
    "bundled-skills": true,
    // the skills of the profile by default (33 in jardis, 25 in core); a list or include/exclude narrows it
    // foundation-* and process-* are always installed
    "git-rules": true,
    // "delegated": the session commits itself, merge and push stay with the human; false removes the git sentences from the router
    "process-docs": "committed"
    // or "local": entries in .git/info/exclude
} }

What the plugin writes for which tool

Tool	Skills	Router	Agent files
Claude Code	`.claude/skills`	`AGENTS.md` via `CLAUDE.md`	`.claude/agents`
Codex	`.agents/skills`	`AGENTS.md`	`.codex/agents`
Cursor	`.agents/skills`	`AGENTS.md`	`.cursor/agents`
GitHub Copilot	`.agents/skills`, `.claude/skills`	`AGENTS.md`	`.github/agents`
Gemini CLI	`.agents/skills`	`AGENTS.md` via `.gemini/settings.json`	`.gemini/agents`

Source: README sections Installation, Supported tools and Reviewer agent files.

Tool coverage

Process building block	Claude Code	Codex CLI/IDE	Cursor	GitHub Copilot	Gemini CLI	Fallback where ◐ / ✘ / ?
Router (`AGENTS.md`) read	✔	✔	✔	✔	◐	Gemini CLI: `context.fileName` in `settings.json` set to `AGENTS.md`
Phase skills (`SKILL.md`) load	✔	✔	✔	✔	✔	Gemini CLI: loads a skill through the `activate_skill` tool and asks you to confirm first
Independent reviewer (sub-agent, fresh context)	✔	✔	✔	✔	✔
Model per reviewer	✔	✔	✔	✔	✔
Board of reviewers in parallel	✔	✔	✔	✔	?	Gemini CLI: not documented by the vendor
Progress / task list	◐	?	?	?	✔	Claude Code: on models the documentation does not name, opt in with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` · Codex, Cursor, Copilot: not documented by the vendor
Plan mode without write access	◐	◐	◐	◐	✔	Claude Code: edits stay blocked until the plan is approved, except in interactive terminal sessions with bypass permissions available · Codex, Cursor: a plan before implementation, no write lock stated · Copilot: not available in Visual Studio
Headless run	✔	✔	✔	✔	✔	`claude -p` · `codex exec` · `agent -p` · `copilot -p` · `gemini -p`
MCP (`jardis mcp`)	✔	✔	✔	✔	✔
`commit-msg` hook with the `Wissen:` note	✔	✔	✔	✔	✔	a Git hook, independent of the tool; it warns and never rejects a commit
Guarantee level	tested Claude Code 2.1.286	documented, not tested	documented, not tested	documented, not tested	documented, not tested	tested: the process was run with the tool and each listed check passed · documented, not tested: the vendor documentation says the tool offers the building block

Not covered

Aider and Continue are not served. Codex Cloud and the Copilot cloud agent are outside the guarantee, even for the tools above.

✔ documented without restriction · ◐ documented with a restriction · ✘ the documentation denies it · ? not found in the vendor documentation. Source: vendor documentation, retrieved 2026-10-01; what the plugin writes for each tool is in the README section Supported tools.

jardis/dev-skills — the process for Jardis projects