@martinffx/atelier 3.0.1 → 3.1.0

package/skills/atelier-setup/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: atelier-setup
-description: Configure a repository's generic agent guidance for Atelier's development workflow. Use only when the user explicitly invokes atelier-setup; it inspects existing repository instructions and domain-document conventions, previews an idempotent project-guidance update, and writes only after approval. It does not install Atelier, configure a harness, or scaffold empty workflow artifacts.
+description: Configure a repository for Atelier's development workflow. Use only when explicitly invoked; inspect existing guidance, issue-tracker and domain-document conventions, preview the proposed configuration, and write only after approval. It does not install Atelier or initialize external tooling.
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Atelier Setup
 
-Set up generic repository guidance that Atelier skills need without taking ownership of the
-developer's installation, harness configuration, or project structure. Explore first, present
-the proposed edit exactly, and write only after the developer approves it.
+Set up repository guidance that Atelier skills need without taking ownership of the developer's
+installation, harness configuration, or project structure. Explore first, present every proposed
+edit exactly, and write only after the developer approves it.
 
 ## 1. Explore
 
@@ -18,6 +19,9 @@ Read the repository before proposing any change:
   heading.
 - Root `CONTEXT.md` and `CONTEXT-MAP.md`.
 - `docs/adr/` and any context-local `docs/adr/` directories.
+- `docs/agents/`, including existing `issue-tracker.md` and `domain.md`.
+- Existing issue-tracker conventions: remotes, issue links in documentation, local issue
+  directories, and project guidance.
 - Genuine monorepo signals: a workspace manifest, or multiple independently deployable packages
   with their own source directories.
 
@@ -33,9 +37,19 @@ Summarize what exists and recommend a domain-document layout:
   contexts. `CONTEXT-MAP.md` belongs at the root and points to each context's `CONTEXT.md` and
   `docs/adr/` directory.
 
-Explain that these documents remain lazy: do not create `CONTEXT.md`, `CONTEXT-MAP.md`, or an ADR
+Explain that domain documents remain lazy: do not create `CONTEXT.md`, `CONTEXT-MAP.md`, or an ADR
 directory until another Atelier skill has resolved terminology or made a decision worth recording.
 
+Select or confirm the issue tracker:
+
+1. If `docs/agents/issue-tracker.md` already defines one, preserve it unless the developer asks to
+   change it.
+2. Otherwise recommend the tracker indicated by existing repository practice, then ask the
+   developer to confirm or describe their tracker.
+3. Accept GitHub, GitLab, local Markdown, another tracker described by the developer, or `none`.
+4. Record the chosen workflow in `docs/agents/issue-tracker.md`; do not install, initialize, or
+   create external tracker resources.
+
 Select the instruction file to edit:
 
 1. If both files exist, ask which file should own the agent guidance; do not duplicate it.
@@ -43,8 +57,13 @@ Select the instruction file to edit:
 3. Otherwise use root `CLAUDE.md` when it exists.
 4. If neither exists, ask which instruction file to create; do not choose on the developer's behalf.
 
-Show the developer the selected file, domain layout, and the exact `## Agent skills` block that will be
-written. Stop and wait for explicit approval.
+Show the developer the selected file, domain layout, and exact contents for:
+
+- the `## Agent skills` block;
+- `docs/agents/issue-tracker.md` using `references/issue-tracker.md`;
+- `docs/agents/domain.md` using `references/domain.md`.
+
+Stop and wait for explicit approval.
 
 ## 3. Write After Approval
 
@@ -58,23 +77,27 @@ Add the following block to the selected instruction file:
 Use `atelier-orchestrator` at the start of development work. It selects an Inline Plan for bounded
 changes or a Spec-backed Plan when durable design and coordination artifacts are warranted.
 
-### Domain documentation
+### Issue tracking
+
+Read `docs/agents/issue-tracker.md` when issue tracking is relevant. It defines this repository's
+tracker workflow; `plan.json` remains authoritative for Spec-backed task details and dependencies.
 
-Before working in a domain area, read root `CONTEXT-MAP.md` when present and follow it to the
-relevant context documentation. Otherwise, read root `CONTEXT.md` when present. Read relevant
-architectural decisions under `docs/adr/` and any context-specific ADR directories.
+### Domain documentation
 
-If these documents do not exist, proceed silently. Create or update them only when domain
-terminology or an architectural decision has been resolved.
+Read `docs/agents/domain.md` before working in a domain area. It defines how to locate and use this
+repository's context documents and ADRs.
 ```
 
-If an `## Agent skills` section already exists, update the `### Planning and implementation` and
-`### Domain documentation` subsections in place rather than appending duplicates. Preserve other
-subsections and all content outside the section, including user edits. Do not create any other
-files or directories.
+If an `## Agent skills` section already exists, update the `### Planning and implementation`,
+`### Issue tracking`, and `### Domain documentation` subsections in place rather than appending
+duplicates. Preserve other subsections and all content outside the section, including user edits.
+
+Create `docs/agents/` when needed, then write the approved tracker and domain documents. Do not
+create any other files or directories.
 
 ## 4. Report
 
-State which instruction file changed and the chosen domain-document layout. Remind the developer
-that the layout is a convention only: the first domain-modelling or architectural-decision task
-creates the relevant documents when it has substantive content.
+State which instruction file and agent documents changed, the selected tracker, and the chosen
+domain-document layout. Remind the developer that the layout is a convention only: the first
+domain-modelling or architectural-decision task creates the relevant documents when it has
+substantive content.

package/skills/atelier-setup/references/domain.md

@@ -0,0 +1,22 @@
+# Domain Documentation
+
+## Layout
+
+- **Mode:** [single-context or multi-context]
+- **Context map:** [path or not used]
+- **System ADRs:** [path]
+- **Context ADRs:** [path pattern or not used]
+
+## Before Domain Work
+
+1. Read the context map when configured, then select the relevant context.
+2. Read that context's `CONTEXT.md` when it exists.
+3. Read ADRs relevant to the work.
+4. Proceed silently when these documents do not yet exist.
+
+## Ownership
+
+- `CONTEXT.md` records domain language, distinctions, and business invariants.
+- `CONTEXT-MAP.md` maps bounded contexts to their context documents and ADRs.
+- ADRs record architectural decisions and trade-offs.
+- This file only tells agents how to locate and consume those documents.

package/skills/atelier-setup/references/issue-tracker.md

@@ -0,0 +1,35 @@
+# Issue Tracker
+
+## Tracker
+
+- **Provider:** [GitHub, GitLab, local Markdown, another tracker, or none]
+- **Location:** [repository, project, URL, or local directory]
+- **Tool or procedure:** [CLI, web workflow, or local-file convention]
+- **Mirror Spec-backed tasks:** [yes or no]
+
+## Authority
+
+`plan.json` is the source of truth for Spec-backed task descriptions, dependencies, and
+validation. Tracker entries only mirror execution state when mirroring is enabled.
+
+## Operations
+
+- **Create:** [how to create an issue or task]
+- **Read:** [how to retrieve it]
+- **Update:** [how to change status or add a note]
+- **Complete:** [how to close it]
+- **Dependencies:** [how blockers are represented]
+
+## Status Mapping
+
+| Plan state | Tracker state |
+|------------|---------------|
+| Ready | [state] |
+| In progress | [state] |
+| Blocked | [state] |
+| Complete | [state] |
+
+## Constraints
+
+- [Required approvals, project conventions, or known limitations]
+- Do not store credentials, tokens, or other secrets in this document.

package/skills/code-commit/SKILL.md

@@ -38,7 +38,7 @@ behavior, motivation, or important implementation decision rather than restating
 | `build` | Build system or dependencies |
 | `revert` | Reverting a prior commit |
 
-For breaking changes, add `!` after the scope and include a `BREAKING CHANGE:` footer.
+Breaking changes may use `!` after the type or scope, a `BREAKING CHANGE:` footer, or both.
 Include issue footers such as `Closes #123` only when the issue is known.
 
 ## Create a Commit
@@ -76,8 +76,9 @@ Before making any write, show:
 
 Ask for approval unless the user explicitly authorizes committing immediately. After
 approval, stage only the files for the approved commit with `git add -- <paths>` and
-commit with the proposed title and body. Do not amend, rebase, push, or include
-unapproved files.
+inspect `git diff --cached --name-status` and `git diff --cached` again. If the staged snapshot
+contains any unapproved file, stop and ask how to handle it. Then commit with the proposed title
+and body. Do not amend, rebase, push, or include unapproved files.
 
 Repository commit hooks are the final message validation when configured. Never bypass
 a failing hook. Report the commit hash on success; report the error and leave changes

package/skills/code-pull-request/references/common.md

@@ -22,10 +22,10 @@ Scan the push URLs for the platform host — don't assume the remote is named
 ## Determine the Base Branch
 
 ```bash
-base=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+base=$(git symbolic-ref --quiet "refs/remotes/<remote>/HEAD" 2>/dev/null | sed 's@^refs/remotes/<remote>/@@')
 if [ -z "$base" ]; then
   for candidate in main master; do
-    git rev-parse --verify --quiet "origin/$candidate" >/dev/null && base=$candidate && break
+    git rev-parse --verify --quiet "<remote>/$candidate" >/dev/null && base=$candidate && break
   done
 fi
 echo "$base"
@@ -59,7 +59,7 @@ gh pr view --json state,number,url,headRefName
 GitLab:
 
 ```bash
-glab mr view --json state,iid,web_url,source_branch
+glab mr view --output json
 ```
 
 - **Open** → use this PR/MR number/URL for comment and merge workflows.
@@ -73,4 +73,4 @@ glab mr view --json state,iid,web_url,source_branch
 ## Safety Guard
 
 Refuse to operate from the default branch — that's almost always a mistake. Ask the
-human to switch to a feature branch first.
+human to switch to a feature branch first.

package/skills/code-pull-request/references/create-pr.md

@@ -15,13 +15,13 @@ gh pr view --json state,number,url
 
 GitLab:
 ```bash
-glab mr view --json state,iid,web_url
+glab mr view --output json
 ```
 
 - **Open** → show the URL, stop. Don't create a duplicate.
 - **Closed/merged** → check for new commits since the PR was closed:
   ```bash
-  git log --oneline origin/<base>..HEAD
+  git log --oneline <remote>/<base>..HEAD
   ```
   New commits exist → proceed to create a new PR.
   No new commits → tell the human, stop.
@@ -61,9 +61,9 @@ ls PULL_REQUEST_TEMPLATE.md 2>/dev/null
 ## Step 3: Generate Title and Body
 
 ```bash
-git log --oneline origin/<base>..HEAD            # commit list
-git log origin/<base>..HEAD --format='%H %s%n%b'  # full commit messages
-git diff --stat origin/<base>...HEAD             # changed files summary
+git log --oneline <remote>/<base>..HEAD            # commit list
+git log <remote>/<base>..HEAD --format='%H %s%n%b' # full commit messages
+git diff --stat <remote>/<base>...HEAD             # changed files summary
 ```
 
 Derive the title from the most significant conventional commit. If commits are
@@ -85,15 +85,15 @@ Fill the body (template sections or fallback) from the commits and diff:
 
 ## Step 4: Create the PR
 
-Push the branch first if it isn't on the remote:
+Show the human the selected remote, branch, generated title, and body before any write. Ask for
+approval to push and create the PR/MR, or proceed if they explicitly said "just do it" up front.
+
+Push the branch only after that approval if it is not on the remote:
 
 ```bash
-git push -u origin <branch-name>
+git push -u <remote> <branch-name>
 ```
 
-**Show the human the generated title and body before creating.** Ask for confirmation,
-or proceed if they said "just do it" up front.
-
 ### GitHub
 
 | Mode | Command |
@@ -107,16 +107,16 @@ or proceed if they said "just do it" up front.
 | Mode | Command |
 |------|---------|
 | Auto-fill | `glab mr create --fill` |
-| Inline | `glab mr create --title "<title>" --description "$(cat <body-file>)"` |
-| Draft | `glab mr create --draft --title "<title>" --description "$(cat <body-file>)"` |
+| Inline | Invoke `glab mr create` with title and description passed as separate arguments by the active command runner. |
+| Draft | Invoke `glab mr create --draft` with title and description passed as separate arguments by the active command runner. |
 
 Default to inline with the generated body. **Never pass a multi-line body directly
 in the command string** (`--body "<body>"`) — quotes, backticks, and `$` in
 Markdown break shell quoting. Write the body to a temp file first, then pass it
-via stdin (`gh --body-file -`) or command substitution (`glab` has no
-description-file flag). Reserve direct inline strings for one-line bodies.
+via stdin (`gh --body-file -`). For GitLab, use the active command runner's argument array rather
+than constructing a shell command; never interpolate the body through command substitution.
 
 Use `--fill` when commits are clean and the body would be redundant. Use `--draft`
 when the human signals work in progress.
 
-After creation, show the PR/MR URL to the human. Done.
+After creation, show the PR/MR URL to the human. Done.

package/skills/code-pull-request/references/merge-pr.md

@@ -73,14 +73,14 @@ Ask for explicit confirmation before running the merge command.
 
 ### GitHub
 ```bash
-gh pr merge <number> --squash --delete-branch
+gh pr merge <number> --squash --delete-branch --match-head-commit <approved-head-sha>
 ```
 Alternatives: `--rebase`, `--merge`, `--auto` (merge automatically once required
 checks pass), or `--admin` (forced merge — see Step 2) per the human's request.
 
 ### GitLab
 ```bash
-glab mr merge <iid> --squash --remove-source-branch
+glab mr merge <iid> --squash --remove-source-branch --sha <approved-head-sha>
 ```
 Alternatives: `--rebase`, or `--auto-merge` (merge once the pipeline succeeds —
 already the default while a pipeline is running) per the human's request.
@@ -91,4 +91,4 @@ already the default while a pipeline is running) per the human's request.
 
 Show the human the merge result — the merge commit SHA, the target branch tip, and
 whether the source branch was deleted. Suggest switching back to the base branch
-locally (`git checkout <base> && git pull`) if the source branch was removed. Done.
+locally (`git checkout <base> && git pull`) if the source branch was removed. Done.

package/skills/code-pull-request/references/read-comments.md

@@ -27,7 +27,7 @@ Inline review comments (file/line threads) — `--json comments` does NOT includ
 them, so fetch them separately:
 
 ```bash
-gh pr view <number> --json reviewThreads,reviews
+gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments
 ```
 
 Or, for a readable summary of top-level comments:
@@ -58,4 +58,4 @@ Show each comment with:
 - **File/line** (for inline review comments)
 
 Newest first. Group inline review comments by file/line, and threads by their
-parent comment. Don't post anything — this is read-only.
+parent comment. Don't post anything — this is read-only.

package/skills/code-review/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: code-review
-description: Multi-agent code review with parallel specialized reviewers, architecture validation, and challenge validation. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to review findings. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes.
+description: Multi-agent code review with parallel specialized reviewers, architecture validation, challenge validation, and durable handling of previously decided findings. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to findings and record intentional non-fix decisions beside the relevant code. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes or adding decision comments.
 argument-hint: "rq [branch] | rs"
 user-invocable: true
 ---
 
 # Code Review Skill
 
-Multi-agent code analysis with parallel reviewers and challenge validation.
+Multi-agent code analysis with a simplicity gate, focused reviewers, and challenge validation.
 
 Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents/SKILL.md).
 
@@ -35,24 +35,43 @@ Use these concrete harness subagent types. If an exact match is unavailable, use
 | `subagent_type` | Purpose |
 |-----------------|---------|
 | `sentinel` | Triage only: changed-file analysis, context retrieval, reviewer selection |
-| `oracle` | Parallel reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
+| `oracle` | Reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
 | `architect` | Architecture, design-boundary, data-model, and API-contract review |
 
 Reviewer names such as `Security`, `Correctness`, `Maintainability`, and `PerformanceOperator` are prompt personas, not subagent types. Do not use `general`; it is not a harness agent.
 
+`Simplicity` is a mandatory reviewer persona for migrations, refactors, and architectural
+changes. Run it before the other reviewers; do not include it in the parallel reviewer batch.
+
+## Review Priority
+
+Review in this order:
+
+1. User goal and prior behavior
+2. Necessity and deletion
+3. Correctness and security
+4. Architecture
+5. SDD compliance
+
+Treat the SDD as evidence, not as authority for whether code is necessary. A finding that
+would expand behavior or infrastructure requires user approval. Never apply it as an ordinary
+review fix.
+
 ### rq (Request Review) Subagents
 
 | Step | Parallel | Purpose |
 |------|----------|---------|
 | 1. Triage | No | Detect context, select reviewers, identify relevant skills to look for |
-| 2. Reviewers | Yes (per reviewer) | Specialty analysis using reviewer personas |
-| 3. Synthesis | No | Deduplicate findings inline |
-| 4. Architect | No | Architecture review |
-| 5. Challenge | No | Validate findings with sequential-thinking |
+| 2. Simplicity | No | Mandatory necessity and deletion review for migrations, refactors, and architectural changes |
+| 3. Reviewers | Yes (per reviewer) | Correctness, security, and other specialty analysis |
+| 4. Synthesis | No | Deduplicate findings inline |
+| 5. Architect | No | Architecture review |
+| 6. SDD + Challenge | No | Check SDD compliance last, then validate findings |
 
 ### rs (Respond to Review)
 
-No subagents. Interactive interview mode — see [rs.md](./references/rs.md).
+No subagents. Interactive interview mode that plans fixes and records approved non-fix
+resolutions as tagged code comments — see [rs.md](./references/rs.md).
 
 ## Dispatch Patterns
 

package/skills/code-review/references/output.md

@@ -12,6 +12,23 @@
 - Files reviewed: N
 - Findings: N Critical, N High, N Medium, N Low
 - Pre-existing: N | Introduced: N
+- Honored decisions: N
+
+## Unnecessary scope
+
+- {Unrequested behavior or infrastructure, or `None`}
+
+## Deletion candidates
+
+- {Files, symbols, wrappers, or tests that can be removed, or `None`}
+
+## Smallest viable alternative
+
+{The smallest implementation that preserves the user goal and prior behavior, or `None`}
+
+## Required SDD corrections
+
+- {Changes needed so the SDD records the smaller result, or `None`}
 
 ## Critical (Fix before merge)
 
@@ -28,6 +45,8 @@
   {Detailed explanation of why this was flagged}
   </details>
 - **Suggestion**: {How to fix}
+- **Requires user approval**: {Yes when the suggestion expands behavior or infrastructure; otherwise No}
+- **Prior decision reopened**: {Why the recorded rationale no longer applies; omit when not applicable}
 
 ## High Priority
 
@@ -45,8 +64,17 @@
 - {What the code does well}
 - {Smart patterns to keep}
 - {Good practices observed}
+
+## Honored Decisions
+
+- `{comment-file}:{line}` — {Concern}: {Short rationale and why it still applies}
 ```
 
+Omit the **Honored Decisions** section when there are no honored decisions. Keep each entry to
+one compact bullet; do not repeat the full finding, impact, reasoning, or suggestion.
+Severity and pre-existing/introduced statistics count active findings only.
+Always render the four simplicity sections, using `None` when no evidence supports an item.
+
 ---
 
 ## Inline Finding Format
@@ -60,6 +88,8 @@ Pre-existing: {Yes/No}
 Issue: {Brief description}
 Reasoning: {Why this matters}
 Suggestion: {Fix}
+Requires user approval: {Yes/No}
+Prior decision reopened: {Why the recorded rationale no longer applies; omit when not applicable}
 ```
 
 ---
@@ -98,6 +128,9 @@ Each finding includes a collapsible section with:
 3. **Evidence**: Code snippets, references, or examples
 4. **Alternative view**: If uncertain, what else to consider
 
+When a recorded decision is reopened, also identify the comment location and the evidence that
+invalidated its rationale or met its reconsideration condition.
+
 Example:
 ```markdown
 <details>
@@ -130,6 +163,23 @@ Implements OAuth login flow with token refresh. Generally well-structured with p
 - Files reviewed: 1
 - Findings: 1 Critical, 1 High, 0 Medium, 2 Low
 - Pre-existing: 1 | Introduced: 3
+- Honored decisions: 0
+
+## Unnecessary scope
+
+- None
+
+## Deletion candidates
+
+- None
+
+## Smallest viable alternative
+
+None
+
+## Required SDD corrections
+
+- None
 
 ## Critical (Fix before merge)
 
@@ -198,3 +248,5 @@ Implements OAuth login flow with token refresh. Generally well-structured with p
 2. **Pre-existing detection** requires git blame check (not just diff)
 3. **Extended reasoning** should be collapsible in markdown renderers
 4. **Positive findings** help balance the review tone
+5. **Honored decisions** stay out of active severity counts and are summarized without restating the finding
+6. **Expansion findings** require user approval even when an SDD proposes the expansion