chore: render agentic engineering template

.codespellrc

@@ -0,0 +1,2 @@
+[codespell]
+ignore-words-list = socio-economic

.copier-answers.agentic.yml

@@ -0,0 +1,8 @@
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+_commit: f4330ec
+_src_path: https://github.com/frankify-app/agentic-engineering-template
+agentic_precommit: prek
+agentic_project_description: Canonical agent skills repo for agentic engineering
+agentic_project_name: Skills
+agentic_project_slug: skills
+agentic_repo_owner: frankify-app

.editorconfig

@@ -0,0 +1,24 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[*.{json,js,mjs,toml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab

.markdownlint-cli2.yaml

@@ -0,0 +1,17 @@
+# https://github.com/DavidAnson/markdownlint-cli2
+config:
+  default: true
+  MD013: false # line-length — agent docs use long URLs and table rows
+
+globs:
+  - "**/*.md"
+  - "**/*.markdown"
+
+# Skip git-ignored paths (e.g. _input/, _references/) since the hook now globs
+# instead of receiving the tracked-file list from prek.
+gitignore: true
+
+ignores:
+  - CHANGELOG.md
+  - .copier-answers.agentic.yml
+  - .all-contributorsrc

.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+# See https://pre-commit.com for more information
+exclude: "CHANGELOG.md|.copier-answers.agentic.yml|.all-contributorsrc"
+default_stages: [pre-commit]
+default_install_hook_types: [pre-commit, commit-msg]
+
+ci:
+  autofix_commit_msg: "chore(pre-commit.ci): auto fixes"
+  autoupdate_commit_msg: "chore(pre-commit.ci): pre-commit autoupdate"
+
+repos:
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.24.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies: ["@commitlint/config-conventional"]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-json
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.22.0
+    hooks:
+      - id: markdownlint-cli2
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.37.1
+    hooks:
+      - id: yamllint
+        args: [--strict]
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      # Lint GitHub Actions workflows under .github/workflows/.
+      - id: actionlint
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell

.yamllint.yaml

@@ -0,0 +1,15 @@
+# https://yamllint.readthedocs.io/
+extends: default
+
+rules:
+  # Config/CI YAML uses long URLs and pinned action SHAs; matches the
+  # MD013 (line-length) opt-out applied to the Markdown docs.
+  line-length: disable
+  # Allow both `true/false` and other truthy spellings without complaint.
+  truthy:
+    check-keys: false
+  # The repo's YAML omits the `---` document marker by convention.
+  document-start: disable
+  # Existing configs use single-space inline comments (`# ...`).
+  comments:
+    min-spaces-from-content: 1

AGENTS.md

@@ -0,0 +1,139 @@
+# Skills — Agent Guidelines
+
+Repo: <https://github.com/frankify-app/skills>
+
+## Project Specifics
+
+### Terminology
+
+Ubiquitous language is defined in docs/glossary/. Use
+
+```bash
+uvx disambiguate <term>
+```
+
+to get a topologically ordered glossary disambiguating all relevant terms
+to understand the given term.
+
+Before working on a ticket, run:
+
+```bash
+uvx disambiguate --from <ticket-file>
+```
+
+or for GitHub issues:
+
+```bash
+ghx issue view <number> --json body -q .body | uvx disambiguate --from -
+```
+
+to resolve all referenced terms at once.
+
+### Architecture
+
+Read [docs/architecture.md](docs/architecture.md) before touching any code.
+
+## Rules
+
+- Small, single-purpose files
+- Readability over brevity — straightforward, easy-to-follow code. No compact "one-liners" stretching across multiple lines (e.g. nested ternaries). Stretching across multiple lines is only allowed if it aids readability.
+- All routes and non-trivial functions: docstring contracts (params, returns, errors)
+- Test cases cover edge cases and every `@returns` line
+
+### Errors
+
+- Forward all errors with full detail + variable values, never swallow or catch, let exceptions propagate with their full traceback to make proper debugging possible
+- Never catch exceptions if they are actual errors that can't be handled
+- Include relevant variable values in error messages, e.g. for JS/TS:
+  `"Failed to fetch peers for workspace_id=${workspace_id}: ${e}"`
+
+## Skills
+
+Live in `.agents/skills/`. Synced using `npx skills update -p -y` — don't edit skill files, add repo-local overrides in AGENTS.md
+1% rule: if skill might apply, load it.
+
+**Loading:** Use platform skill tool if available, else read `.agents/skills/<name>/SKILL.md` directly.
+
+| Skill                    | Trigger                                                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `tdd`                    | Test-driven-development for any implementation                                                     |
+| `documenting-decisions`  | Any implementation task — place `DECISION:` markers                                                |
+| `requesting-code-review` | After completing implementation                                                                    |
+| `caveman`                | Compact wording when writing prose (issues description, PR description, comments on repo or code)  |
+
+## Git
+
+- Branch: `<agent>/<issue-number>-<desc>` (e.g. `hermes/42-fix-auth`, `claude/42-fix-auth`)
+- Never push to `main`
+- Create PR immediately on branch creation
+- Commits: conventional commits
+- Document unexpected encounters and design decisions in commit message as well as PR/Issue
+
+### Agentic Engineering Workflow
+
+Use `ghx` for all repository interaction. `gh` and `tea` are disabled — calling them tells you to use `ghx` instead.
+
+`ghx` exposes a curated subset of `gh`'s verbs (plus a few additions, e.g. `--code-comment`) and presents the **same `gh`-style interface against both GitHub and Forgejo**, so you never need to know which host the repo is on. It is **not** a full `gh` replacement: it has only the verbs listed below. If a command isn't in this list, `ghx` doesn't have it — don't fall back to `gh`/`tea`.
+
+#### Available `ghx` verbs
+
+- **issues:** `issue create`, `issue view` (`--comments`), `issue list`, `issue comment`, `issue edit`
+- **pull requests:** `pr create`, `pr view` (`--comments`), `pr list`, `pr comment`, `pr edit`, `pr review` (`--body`, repeatable `--code-comment path:line:text`), `pr checks`, `pr status`
+- **CI:** `run list`, `run view`
+
+Use `run list` / `run view` for workflow-run detail; use `pr checks` / `pr status` for a PR's check rollup.
+
+The modes below are the kinds of work the user will ask for. **Each runs in its own session — possibly a different model or agent** (Review especially). Follow the named skills at each step.
+
+#### Plan
+
+- Explore the codebase. Flag `DECISION:SCOPE` when resolving ambiguities. Use the `documenting-decisions` skill (refs: `pre-approval-gate.md`, `scope-interpretation.md`).
+- Write an issue → `ghx issue create`
+- Set issue metadata → `ghx issue edit` (labels/assignees/milestone)
+
+#### Implement
+
+- Read the given issue and comments → `ghx issue view --comments`
+- Do Test-Driven Development per the `tdd` skill.
+- Implement the minimal code to pass tests, then the remaining code per the ticket spec. Place `DECISION:` markers per the `documenting-decisions` skill (refs: `decision-markers.md`, `marker-examples.md`).
+- Commit discipline:
+  - One test → one commit → one implementation for that test → one commit
+  - `prek` must pass on every commit (lint/format hooks only — prek never runs unit tests).
+  - TDD red-step commits are expected and required (a commit whose new tests fail but whose lint/format passes). **CI evaluates at PR HEAD, not per-commit**, so a red-step commit does not constitute a CI failure — do not treat it as one.
+  - Don't fix lint manually — run the formatter. Only touch code directly if the tools can't resolve it.
+- Push → `git push` *(plain git; git is not routed through `ghx`)*
+- Create the PR if not already present, and link it to the issue both ways → `ghx pr create` (start with `Closes #<number>` in description), then `ghx issue edit` if a back-reference is needed. **If a PR already exists for this branch, do not create or re-link it** — skip to CI.
+  PR body must include:
+  - `Closes #<number>`.
+  - Any obstacles that diverged from the initial plan, and — in the rare event spec deviation was unavoidable — what deviated and why.
+  - All `DECISION:` markers present in the diff, rendered per the `documenting-decisions` skill format.
+- Check CI → `ghx run list` / `ghx run view` (or `ghx pr checks` once the PR exists).
+- If CI fails, fix it by re-entering this **Implement** workflow.
+
+#### Review
+
+- Read the given issue and comments → `ghx issue view --comments`
+- Review the PR and give Critical / Important feedback per the `requesting-code-review` skill.
+- Submit it as a single review → `ghx pr review`:
+  - PR-level summary feedback → `--body "..."`
+  - Feedback tied to specific lines → repeatable `--code-comment path:line:text`
+  - Put both in the same `ghx pr review` call; don't split a review across `pr review` and `pr comment`.
+
+#### Apply Review Comments
+
+- Read the given issue and comments → `ghx issue view --comments`
+- Read PR comments and code comments → `ghx pr view --comments`
+- If the review uncovers inconsistencies in the issue, **comment** on it freely → `ghx issue comment`
+- Only **edit** issue content when the user explicitly requests it → `ghx issue edit`. Editing is gated on explicit request because it can overwrite human-authored intent; commenting is always safe, editing is not.
+- Then re-enter the **Implement** workflow.
+
+## Dependencies
+
+Add packages using the package manager only, never edit requirements/dependencies directly (since your knowledge cut-off prevents you from knowing the latest version of the packages).
+
+## Documentation
+
+- All non-trivial functions must have contracts in the function doc string
+- Document all params, return shapes, and every possible error response
+- Test cases must cover edge cases for inputs and every @returns line in the contract
+- Non-trivial decisions or behavior should be documented via inline comments

CLAUDE.md

@@ -0,0 +1,7 @@
+# Claude Code Specific Project Instructions
+
+**First:** Read `AGENTS.md`. Follow all instructions and skills there.
+
+## Pull Requests
+
+Share PR URL in response to user.

commitlint.config.mjs

@@ -0,0 +1,8 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "header-max-length": [0, "always", Infinity],
+    "body-max-line-length": [0, "always", Infinity],
+    "footer-max-line-length": [0, "always", Infinity],
+  },
+};

docs/architecture.md

@@ -0,0 +1,3 @@
+# Architecture
+
+Read [Skills](glossary/skills.md) and this document before touching code.

docs/glossary/.markdownlint-cli2.yaml

@@ -0,0 +1,4 @@
+# Glossary entries start with `##` per the Disambiguate definition,
+# so the first-line-h1 rule does not apply here.
+config:
+  MD041: false

docs/glossary/skills.md

@@ -0,0 +1,3 @@
+## Skills
+
+Canonical agent skills repo for agentic engineering

scripts/doctor.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Host-tool checks for agentic-engineering repos.
+# Default: report only. --install / --fix: bootstrap missing host CLIs (never project deps).
+set -euo pipefail
+
+INSTALL=false
+if [[ "${1:-}" == "--install" || "${1:-}" == "--fix" ]]; then
+    INSTALL=true
+fi
+
+# Required host tools for this generated project.
+REQUIRED_TOOLS=(git npx uvx gh)
+REQUIRED_TOOLS+=(prek)
+
+pass=0
+fail=0
+
+check_tool() {
+    local tool=$1
+    if command -v "$tool" >/dev/null 2>&1; then
+        echo "✓ $tool"
+        pass=$((pass + 1))
+        return 0
+    fi
+    echo "✗ $tool"
+    fail=$((fail + 1))
+    return 1
+}
+
+warn_tool() {
+    local tool=$1
+    local message=$2
+    if command -v "$tool" >/dev/null 2>&1; then
+        echo "✓ $tool"
+        pass=$((pass + 1))
+    else
+        echo "⚠ $tool — $message"
+    fi
+}
+
+detect_pkg_manager() {
+    if [[ "$(uname -s)" == "Darwin" ]] && command -v brew >/dev/null 2>&1; then
+        echo brew
+    elif command -v apt-get >/dev/null 2>&1; then
+        echo apt
+    elif command -v apt >/dev/null 2>&1; then
+        echo apt
+    else
+        echo unknown
+    fi
+}
+
+manual_install_hint() {
+    local tool=$1
+    case "$tool" in
+        git) echo "Install git via your platform package manager." ;;
+        gh) echo "brew install gh  OR  sudo apt-get install -y gh" ;;
+        npx) echo "brew install node  OR  sudo apt-get install -y npm" ;;
+        uvx) echo "brew install uv  OR  curl -LsSf https://astral.sh/uv/install.sh | sh" ;;
+        prek) echo "brew install prek  OR  see https://github.com/j178/prek#installation" ;;
+        *) echo "Install $tool manually." ;;
+    esac
+}
+
+install_tool() {
+    local tool=$1
+    local mgr
+    mgr=$(detect_pkg_manager)
+
+    if [[ "$mgr" == unknown ]]; then
+        echo "Cannot auto-install $tool: unrecognized platform or package manager."
+        manual_install_hint "$tool"
+        return 1
+    fi
+
+    case "$tool" in
+        git)
+            case "$mgr" in
+                brew) brew install git ;;
+                apt) sudo apt-get install -y git ;;
+            esac
+            ;;
+        gh)
+            case "$mgr" in
+                brew) brew install gh ;;
+                apt) sudo apt-get install -y gh ;;
+            esac
+            ;;
+        npx)
+            case "$mgr" in
+                brew) brew install node ;;
+                apt) sudo apt-get install -y npm ;;
+            esac
+            ;;
+        uvx)
+            case "$mgr" in
+                brew) brew install uv ;;
+                apt) curl -LsSf https://astral.sh/uv/install.sh | sh ;;
+            esac
+            ;;
+        prek)
+            case "$mgr" in
+                brew) brew install prek ;;
+                apt)
+                    echo "Cannot auto-install prek via apt."
+                    manual_install_hint prek
+                    return 1
+                    ;;
+            esac
+            ;;
+        *)
+            echo "No install recipe for $tool."
+            return 1
+            ;;
+    esac
+}
+
+echo "agentic doctor — host tool check"
+echo
+
+missing=()
+for tool in "${REQUIRED_TOOLS[@]}"; do
+    if ! check_tool "$tool"; then
+        missing+=("$tool")
+    fi
+done
+
+warn_tool ghx "not installed (deferred; agents use ghx for repo interaction)"
+
+echo
+echo "Summary: $pass ok, $fail required missing"
+
+if [[ ${#missing[@]} -eq 0 ]]; then
+    exit 0
+fi
+
+if [[ "$INSTALL" != true ]]; then
+    echo
+    echo "Re-run with --install to bootstrap missing host tools."
+    for tool in "${missing[@]}"; do
+        manual_install_hint "$tool"
+    done
+    exit 1
+fi
+
+echo
+echo "Installing missing tools..."
+install_failed=false
+for tool in "${missing[@]}"; do
+    if ! install_tool "$tool"; then
+        install_failed=true
+    fi
+done
+
+if [[ "$install_failed" == true ]]; then
+    exit 1
+fi
+
+echo
+echo "Re-checking..."
+exec "$0"
+

skills-lock.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "skills": {
+    "caveman": {
+      "source": "frankify-app/skills",
+      "sourceType": "github",
+      "skillPath": "derived/caveman/SKILL.md",
+      "computedHash": "eac65828cc17c46ec0353d76735813f7c95e88f57226fd5c665254b7bdbc737b"
+    },
+    "documenting-decisions": {
+      "source": "frankify-app/skills",
+      "sourceType": "github",
+      "skillPath": "original/documenting-decisions/SKILL.md",
+      "computedHash": "3ba6f8d16a89f3dbc1eee34747eb5882e08dff5ccfba71fddf71009915311eef"
+    },
+    "requesting-code-review": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/requesting-code-review/SKILL.md",
+      "computedHash": "cde520e9118d7e6b74b5ab0123cff2f68d9c07bddb3f82c997753b6126600aed"
+    },
+    "tdd": {
+      "source": "frankify-app/skills",
+      "sourceType": "github",
+      "skillPath": "derived/tdd/SKILL.md",
+      "computedHash": "45895388d0897cc91e32cbce796a31354e28d0ec770a83543d1122aa324f430a"
+    }
+  }
+}