@martinffx/atelier 1.2.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "cli",
     "claude-code",
     "opencode",
+    "codex",
     "ai-agents",
     "spec-driven-development"
   ],
@@ -19,6 +20,7 @@
     "dist/",
     "skills/",
     "agents/",
+    ".codex-plugin/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -28,6 +30,8 @@
   },
   "scripts": {
     "build": "bun build ./src/atelier.ts --outdir ./dist --target bun",
+    "clean": "rm -rf dist .agents .claude .codex .opencode hooks && rm -f *.log .DS_Store",
+    "cli": "bun src/atelier.ts",
     "typecheck": "tsgo --noEmit",
     "test": "bun test",
     "prepare": "simple-git-hooks"
@@ -39,6 +43,7 @@
     "commander": "^13.1.0",
     "gray-matter": "^4.0.3",
     "inquirer": "^12.5.2",
+    "smol-toml": "^1.7.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {

package/skills/code-commit/SKILL.md

@@ -6,113 +6,116 @@ user-invocable: true
 
 # Conventional Commit Skill
 
-Generate and validate commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+Create coherent, reviewable commits that follow the
+[Conventional Commits](https://www.conventionalcommits.org/) specification.
+Message syntax matters, but the selected changes must tell one clear story too.
 
-## Conventional Commit Format
+## Message Format
 
-```
-<type>(<scope>): <subject>
+Every generated commit has a title and body:
 
-[optional body]
+```
+<type>(<scope>): <imperative title>
 
-[optional footer(s)]
+<1-5 lines describing the change and, when useful, its reason or effect>
 ```
 
-### Types
+Use a lowercase scope that identifies the affected component. The title is concise,
+imperative, lowercase, and has no trailing period. The body is concrete: explain the
+behavior, motivation, or important implementation decision rather than restating the title.
 
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `fix` | Bug fix |
+| Type | Use for |
+|------|---------|
+| `feat` | New user-facing capability |
+| `fix` | Corrected behavior |
 | `docs` | Documentation only |
-| `style` | Code style (formatting, semicolons, etc.) |
-| `refactor` | Code change that neither fixes nor adds |
-| `test` | Adding or updating tests |
-| `chore` | Build, tooling, dependencies |
+| `style` | Formatting only |
+| `refactor` | Restructuring without behavior change |
+| `test` | Tests only |
+| `chore` | Maintenance or tooling |
 | `perf` | Performance improvement |
-| `ci` | CI configuration changes |
+| `ci` | Continuous integration configuration |
 | `build` | Build system or dependencies |
-| `revert` | Reverting a previous commit |
+| `revert` | Reverting a prior commit |
 
-### Rules
+For breaking changes, add `!` after the scope and include a `BREAKING CHANGE:` footer.
+Include issue footers such as `Closes #123` only when the issue is known.
 
-- **Subject**: Short description, imperative mood, lowercase, no period at end
-- **Scope**: Optional, lowercase, describes what was changed (e.g., `auth`, `api`, `ui`)
-- **Breaking changes**: Add `!` after type/scope: `feat(auth)!: change API`
-- **Footer**: For breaking changes (`BREAKING CHANGE:`) or issue references (`Closes #123`)
+## Create a Commit
 
-## Operations
+When the user asks to commit, first inspect the complete worktree:
 
-### 1. Generate Commit from Diff
+1. Run `git status --short`.
+2. Read both `git diff --cached` and `git diff` so pre-staged work is not mistaken for the entire change.
+3. List untracked files with `git ls-files --others --exclude-standard` and inspect relevant ones.
+4. Read recent subjects with `git log --oneline -10` to match established scopes and wording.
+5. Flag likely secrets, credentials, local configuration, or generated output. Do not stage them without explicit direction.
 
-When user wants to commit changes:
+### Decide Whether to Split
 
-1. Run `git status` to see changed files
-2. Run `git diff --staged` for staged changes
-3. Analyze what changed to determine:
-   - **Type**: Which type best describes the changes?
-   - **Scope**: What area was affected? (optional)
-   - **Subject**: What was done? (imperative: "add" not "added")
-4. Create a conventional commit message
-5. Run `git commit -m "<message>"`
+Default to one commit containing all intended, related changes. Look for an obvious
+file-level split only when changes are independent and each group can stand alone.
 
-**Example:**
-```
-feat(auth): add JWT token refresh
+Keep these together:
 
-Implements token refresh endpoint to extend sessions
-without requiring re-authentication.
+- Implementation and its tests.
+- Documentation that describes the same change.
+- Dependency manifests and their lockfiles.
 
-Closes #142
-```
+Do not invent a split for adjacent work, use hunk-level staging, or force the user
+to reorganize a coherent change. If an obvious split exists, propose each commit with
+its files and full message, then ask once for approval. If not, propose one commit.
+
+### Approve, Stage, Commit
+
+Before making any write, show:
 
-### 2. Validate Commit Message
+- The files in each proposed commit.
+- The full title and 1-5 line body for each commit.
+- Any excluded files and why they are excluded.
 
-When user asks to validate or check a commit message:
+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.
 
-1. Parse the commit message
-2. Check format: `<type>(<scope>): <subject>`
-3. Validate type is from the allowed list
-4. Check subject follows rules (lowercase, imperative, no period)
-5. Flag any issues found
+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
+intact on failure.
 
-### 3. Create Pull Request
+## Validate a Commit Message
 
-When user wants to open a PR or after finishing commits on a feature branch:
+When the user asks to validate a message, check:
 
-1. Verify on a feature branch (not main): `git branch --show-current`
-2. Check for project PR template: `ls .github/PULL_REQUEST_TEMPLATE.md`
-3. Push branch if needed: `git push -u origin <branch>`
-4. Create PR via `gh pr create`:
-   - Use `--fill` if commits are clean (auto-populates title/body)
-   - Use `--draft` for work-in-progress
-   - Use interactive mode if body needs custom content
-5. Show the PR URL to the user
+1. It follows `type(scope): imperative title`.
+2. The type is listed above and the scope is lowercase.
+3. The title is lowercase, imperative, concise, and has no trailing period.
+4. A body follows after a blank line and contains 1-5 meaningful lines.
+5. Breaking changes use both `!` and a `BREAKING CHANGE:` footer.
 
-See [references/pr-workflow.md](references/pr-workflow.md) for full workflow details.
+Return specific corrections and a revised message. When the repository configures
+commitlint, use it as the authoritative validation rule.
+
+### Delegated: Pull Request Creation
+
+If the user wants to create a PR after committing, invoke the
+[code-pull-request](../code-pull-request/SKILL.md) skill. It detects the platform
+(GitHub/GitLab), finds a template, generates the body, and opens the PR via `gh`
+or `glab`.
 
 ## Input Methods
 
 | Input | Action |
 |-------|--------|
-| User says "commit" or "git commit" | Generate from git diff, then commit |
+| User says "commit" or "git commit" | Inspect the worktree, propose coherent commit(s), then commit after approval |
 | User says "validate commit" | Check the commit message format |
 | User pastes commit message | Validate the provided message |
 
-## Auto-Commit Workflow
-
-When generating a commit:
-
-1. Show the user the commit message first
-2. Ask for confirmation before committing (unless user explicitly says "just do it")
-3. Execute `git commit -m "<message>"` after confirmation
-4. Show the result of the commit
-
 ## Error Handling
 
-- If no staged changes: `git status` shows nothing → warn user nothing to commit
-- If git not initialized: Initialize repo or warn user
-- If commit fails: Show error and offer to retry
+- If there are no changes: report that there is nothing to commit.
+- If Git is not initialized: report it; do not initialize a repository unless asked.
+- If a commit fails: show the error, preserve the worktree, and do not bypass hooks.
 
 ## Examples
 
@@ -121,8 +124,7 @@ When generating a commit:
 ```
 fix(auth): resolve login timeout issue
 
-Users were logged out after 5 minutes due to
-incorrect token expiry calculation.
+Correct token expiry calculation so active users are not logged out after five minutes.
 ```
 
 **Input:** "I added a new API endpoint for users"
@@ -130,8 +132,7 @@ incorrect token expiry calculation.
 ```
 feat(api): add user profile endpoint
 
-GET /users/:id returns user profile data including
-name, email, and avatar URL.
+Expose name, email, and avatar URL from `GET /users/:id`.
 
 Closes #89
 ```
@@ -141,8 +142,7 @@ Closes #89
 ```
 feat(auth)!: change token validation endpoint
 
-The /auth/verify endpoint now requires Bearer token
-instead of query parameter.
+Require a Bearer token on `/auth/verify` instead of a query parameter.
 
 BREAKING CHANGE: Clients must update to send
 Authorization header with Bearer token.

package/skills/code-handoff/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "What will the next session be used for?"
 user-invocable: true
 ---
 
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Create `<project-root>/.handoff/` if needed and save the document there with a descriptive `.md` filename.
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 

package/skills/code-pull-request/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: code-pull-request
+description: >
+  Manage GitHub pull requests or GitLab merge requests: create, read/leave/respond to
+  comments, and merge. Triggers on "open a PR", "make a PR", "merge this PR", "merge the
+  MR", "read PR comments", "leave a comment on the PR", "respond to a comment", "ship this",
+  or when a feature branch is ready for review.
+user-invocable: true
+---
+
+# Pull Request / Merge Request Skill
+
+Create, comment on, and merge GitHub pull requests or GitLab merge requests for the
+current branch. Assumes the relevant CLI (`gh` or `glab`) is installed and authenticated.
+
+This skill is **create/read + write-gated**. Every write action (create PR, leave
+comment, respond to comment, merge) requires explicit human confirmation before running.
+
+---
+
+## Start Here
+
+1. Detect the platform and find the current branch's open PR/MR — see
+   [references/common.md](references/common.md).
+2. Pick a workflow:
+
+| Workflow | Reference | Trigger phrases |
+|----------|-----------|------------------|
+| Create PR/MR | [create-pr.md](references/create-pr.md) | "open a PR", "make a PR", "submit for review" |
+| Read comments | [read-comments.md](references/read-comments.md) | "read PR comments", "show MR comments" |
+| Leave a comment | [leave-comment.md](references/leave-comment.md) | "leave a comment", "comment on the PR" |
+| Respond to a comment | [respond-to-comment.md](references/respond-to-comment.md) | "respond to a comment", "reply on the PR" |
+| Merge PR/MR | [merge-pr.md](references/merge-pr.md) | "merge this PR", "ship it", "merge the MR" |
+
+Both GitHub (`gh`) and GitLab (`glab`) are first-class. Every write step pauses for
+human approval before running the CLI command.

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

@@ -0,0 +1,76 @@
+# Common: Platform Detection and PR Lookup
+
+Shared steps used by every workflow. Run these first.
+
+---
+
+## Detect Platform
+
+```bash
+git remote -v
+```
+
+Scan the push URLs for the platform host — don't assume the remote is named
+`origin` (forks and multi-remote setups often use `upstream` or other names):
+
+- Contains `github.com` → use `gh` (GitHub PR)
+- Contains `gitlab` → use `glab` (GitLab MR)
+- Multiple or no matches → ask the human which remote to use.
+
+---
+
+## Determine the Base Branch
+
+```bash
+base=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+if [ -z "$base" ]; then
+  for candidate in main master; do
+    git rev-parse --verify --quiet "origin/$candidate" >/dev/null && base=$candidate && break
+  done
+fi
+echo "$base"
+```
+
+If that's still empty, ask the human what the base branch is.
+
+---
+
+## Preflight the CLI
+
+Confirm the relevant CLI is installed and authenticated before any write:
+
+```bash
+gh auth status     # GitHub
+glab auth status   # GitLab
+```
+
+If not authenticated, stop and tell the human. Don't proceed with writes.
+
+---
+
+## Find the Open PR/MR for the Current Branch
+
+GitHub:
+
+```bash
+gh pr view --json state,number,url,headRefName
+```
+
+GitLab:
+
+```bash
+glab mr view --json state,iid,web_url,source_branch
+```
+
+- **Open** → use this PR/MR number/URL for comment and merge workflows.
+- **Closed/merged** → for merge workflow: check for new commits
+  (`git log --oneline origin/<base>..HEAD`); otherwise stop and tell the human.
+- **None** → for merge workflow: run [create-pr.md](create-pr.md), then continue.
+  For comment workflows: stop — nothing to comment on.
+
+---
+
+## 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.

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

@@ -0,0 +1,122 @@
+# Workflow: Create PR/MR
+
+Create a pull request (GitHub) or merge request (GitLab) for the current branch.
+
+Start with [common.md](common.md) (platform detection, base branch, preflight).
+
+---
+
+## Step 1: Check for Existing PR/MR
+
+GitHub:
+```bash
+gh pr view --json state,number,url
+```
+
+GitLab:
+```bash
+glab mr view --json state,iid,web_url
+```
+
+- **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
+  ```
+  New commits exist → proceed to create a new PR.
+  No new commits → tell the human, stop.
+- **None** → proceed to create.
+
+---
+
+## Step 2: Find a Template
+
+Look for the repo's PR/MR template:
+
+GitHub:
+```bash
+ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
+ls .github/PULL_REQUEST_TEMPLATE/*.md 2>/dev/null
+```
+
+GitLab:
+```bash
+ls .gitlab/merge_request_templates/*.md 2>/dev/null
+ls .gitlab/merge_request_template.md 2>/dev/null
+```
+
+Also check common locations:
+```bash
+ls docs/PULL_REQUEST_TEMPLATE.md 2>/dev/null
+ls PULL_REQUEST_TEMPLATE.md 2>/dev/null
+```
+
+- **Template found** → use it. The CLI will auto-apply it in interactive mode, or
+  fill each section from the commits and diff for inline mode.
+- **No template** → use the fallback template at
+  [default-template.md](default-template.md).
+
+---
+
+## 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
+```
+
+Derive the title from the most significant conventional commit. If commits are
+messy, synthesize from the diff:
+
+```
+<type>(<scope>): <description>
+```
+
+Fill the body (template sections or fallback) from the commits and diff:
+- **Summary** — what and why, one or two sentences
+- **Changes** — bulleted, grouped by area
+- **Testing** — how it was verified (if known)
+- **Checklist** — tests pass, conventional commits, docs updated
+- **Linked issues** — extract `Closes #N`, `Fixes #N`, `Relates to #N` from commit
+  footers
+
+---
+
+## Step 4: Create the PR
+
+Push the branch first if it isn't on the remote:
+
+```bash
+git push -u origin <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 |
+|------|---------|
+| Auto-fill | `gh pr create --fill` |
+| Inline | `gh pr create --title "<title>" --body-file -` (body via stdin) |
+| Draft | `gh pr create --draft --title "<title>" --body-file -` (body via stdin) |
+
+### GitLab
+
+| 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>)"` |
+
+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.
+
+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.

package/skills/code-pull-request/references/default-template.md

@@ -0,0 +1,25 @@
+# Default PR/MR Template
+
+Fallback body template when the repository has no `.github/PULL_REQUEST_TEMPLATE.md`
+or `.gitlab/merge_request_template.md`. Fill each section from the conventional
+commits and diff.
+
+```markdown
+## Summary
+<!-- One or two sentences: what and why -->
+
+## Changes
+<!-- Bulleted, grouped by area. Each bullet self-contained. -->
+-
+
+## Testing
+<!-- How it was verified: test commands run, manual steps, edge cases checked -->
+
+## Checklist
+- [ ] Tests pass
+- [ ] Commits follow conventional format
+- [ ] Documentation updated (if needed)
+
+## Linked Issues
+<!-- Closes #123, Fixes #456, Relates to #789 -->
+```

package/skills/code-pull-request/references/leave-comment.md

@@ -0,0 +1,53 @@
+# Workflow: Leave a Comment
+
+Post a new top-level comment on the current branch's open PR/MR.
+
+Start with [common.md](common.md) (platform detection, find the open PR/MR).
+
+---
+
+## Step 1: Find the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+If none is open, stop — nothing to comment on.
+
+---
+
+## Step 2: Compose the Comment
+
+Ask the human for the comment body. Accept either:
+
+- Their exact text, or
+- A draft you generate (e.g., a status update, summary, or question) that they edit.
+
+Prefer passing the body via stdin or a temp file to avoid shell-escaping issues with
+quotes, backticks, or `$` in the message:
+
+```bash
+gh pr comment <number> --body-file -
+glab mr note <iid> --message-file -   # if supported; otherwise --message
+```
+
+---
+
+## Step 3: Confirm and Post
+
+**Show the human the final comment text and target PR/MR. Ask for confirmation
+before running the write command.**
+
+### GitHub
+```bash
+gh pr comment <number> --body "<body>"
+```
+Or via stdin to avoid escaping:
+```bash
+echo "$body" | gh pr comment <number> --body-file -
+```
+
+### GitLab
+```bash
+glab mr note <iid> --message "<body>"
+```
+
+After posting, show the human the comment URL or the updated PR/MR URL. Done. Do not
+merge or make further changes unless the human asks for another workflow.

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

@@ -0,0 +1,94 @@
+# Workflow: Merge PR/MR
+
+Merge the current branch's open PR/MR after confirming CI is green.
+
+Defaults: **squash merge + delete the source branch**. If CI is pending, abort and
+report — don't block waiting unless the human says otherwise.
+
+Start with [common.md](common.md) (platform detection, base branch, preflight).
+
+---
+
+## Step 1: Find or Create the Open PR/MR
+
+Run the lookup in [common.md](common.md#find-the-open-prmr-for-the-current-branch).
+
+- **Open** → continue to Step 2.
+- **None** → run [create-pr.md](create-pr.md) first, then continue.
+- **Closed/merged** → check for new commits since it was closed
+  (`git log --oneline origin/<base>..HEAD`); stop if none.
+
+---
+
+## Step 2: Check CI Is Green
+
+### GitHub
+```bash
+gh pr checks <number>            # all checks
+gh pr checks <number> --required # the merge gate
+```
+Exit codes for `--required`: 0 = all required checks pass; non-zero includes the
+pending case (exit 8). Use `gh pr checks <number> --watch` to wait if the human
+asks for it.
+
+`--required` only shows required checks. If the full run shows failing **optional**
+checks (lint, coverage, etc.), warn the human before proceeding — don't silently
+ignore them.
+
+### GitLab
+```bash
+glab ci status
+# or
+glab pipeline status
+```
+
+If any required check is **pending**, offer auto-merge instead of a direct merge:
+`gh pr merge --auto` (GitHub) or `glab mr merge --auto-merge` (GitLab) queues the
+merge to run once checks pass. A bare `gh pr merge` fails while required checks
+are pending — "merge anyway" does not work in that state. Note: `glab mr merge`
+enables auto-merge by default while a pipeline is running.
+
+If any required check is **failing**, stop and report the status to the human.
+Don't merge on red. If the human says "merge anyway": on GitHub a forced merge
+requires `--admin` (bypasses branch protection, needs admin rights on the repo) —
+state that implication explicitly before using it. On GitLab, merging on red is
+controlled by project settings — ask the human to fix the pipeline or adjust the
+setting.
+
+---
+
+## Step 3: Confirm Before Merging
+
+**Show the human:**
+- PR/MR URL and number/iid
+- CI status (green/red)
+- Merge strategy (squash by default)
+- Whether the source branch will be deleted
+
+Ask for explicit confirmation before running the merge command.
+
+---
+
+## Step 4: Merge
+
+### GitHub
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+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
+```
+Alternatives: `--rebase`, or `--auto-merge` (merge once the pipeline succeeds —
+already the default while a pipeline is running) per the human's request.
+
+---
+
+## Step 5: Report
+
+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.