From 219aba97e1938328b514b751fc675b14c654b2db Mon Sep 17 00:00:00 2001 From: Rishabh Kumar Date: Mon, 29 Jun 2026 12:09:45 +0530 Subject: [PATCH] feat : add aem-agentify plugin - Add plugins/aem/agentify/ plugin with .claude-plugin/plugin.json - Skill transforms any AEM customer repo into an AI-native one across all AEM types: OSGi bundles, content packages, multi-module Maven, AEM CS, AEM 6.5 - review-governor referenced as an independent skill, not bundled - Update README.md with agentify plugin entry and installation instructions Co-Authored-By: Claude Sonnet 4.6 --- README.md | 90 ++- .../agentify/skills/agentify/CONVENTIONS.md | 536 +++++++++++++++++ plugins/aem/agentify/skills/agentify/PLAN.md | 490 ++++++++++++++++ .../aem/agentify/skills/agentify/README.md | 66 +++ plugins/aem/agentify/skills/agentify/SKILL.md | 303 ++++++++++ .../agentify/references/maven-release.md | 147 +++++ .../skills/agentify/references/phase-1.md | 551 ++++++++++++++++++ .../skills/agentify/references/phase-2.md | 512 ++++++++++++++++ .../skills/agentify/references/phase-3.md | 123 ++++ .../skills/agentify/references/phase-4.md | 185 ++++++ .../agentify/references/plan-reference.md | 75 +++ .../agentify/references/prompt-templates.md | 194 ++++++ .../references/release-skill-template.md | 177 ++++++ .../references/repo-agent-templates.md | 208 +++++++ .../agentify/references/repo-type-guidance.md | 57 ++ .../agentify/references/rules-templates.md | 114 ++++ .../agentify/references/skills-templates.md | 193 ++++++ 17 files changed, 3996 insertions(+), 25 deletions(-) create mode 100644 plugins/aem/agentify/skills/agentify/CONVENTIONS.md create mode 100644 plugins/aem/agentify/skills/agentify/PLAN.md create mode 100644 plugins/aem/agentify/skills/agentify/README.md create mode 100644 plugins/aem/agentify/skills/agentify/SKILL.md create mode 100644 plugins/aem/agentify/skills/agentify/references/maven-release.md create mode 100644 plugins/aem/agentify/skills/agentify/references/phase-1.md create mode 100644 plugins/aem/agentify/skills/agentify/references/phase-2.md create mode 100644 plugins/aem/agentify/skills/agentify/references/phase-3.md create mode 100644 plugins/aem/agentify/skills/agentify/references/phase-4.md create mode 100644 plugins/aem/agentify/skills/agentify/references/plan-reference.md create mode 100644 plugins/aem/agentify/skills/agentify/references/prompt-templates.md create mode 100644 plugins/aem/agentify/skills/agentify/references/release-skill-template.md create mode 100644 plugins/aem/agentify/skills/agentify/references/repo-agent-templates.md create mode 100644 plugins/aem/agentify/skills/agentify/references/repo-type-guidance.md create mode 100644 plugins/aem/agentify/skills/agentify/references/rules-templates.md create mode 100644 plugins/aem/agentify/skills/agentify/references/skills-templates.md diff --git a/README.md b/README.md index 63cfd268..ea1e3ebe 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ Repository of Adobe skills for AI coding agents. /plugin install app-builder@adobe-skills /plugin install aem-cloud-service@adobe-skills /plugin install aem-6-5-lts@adobe-skills +/plugin install aem-agentify@adobe-skills ``` ### Vercel Skills (npx skills) @@ -184,6 +185,34 @@ If `AGENTS.md` already exists it is never overwritten. See `plugins/aem/cloud-service/skills/ensure-agents-md/` for the skill, template, and module catalog. +### AI-Native Repository Setup — agentify + +The `agentify` skill transforms any AEM customer repository into one that AI agents can navigate +and contribute to independently. It runs a four-phase structured workflow — always with user +approval before writing — that produces the full AI-native surface for the repo: + +| Phase | Output | +|-------|--------| +| Phase 0 — Assess | Repo type classification (OSGi bundle, content package, multi-module Maven, AEMaaCS project, etc.) and inventory of existing AI-native files | +| Phase 1 — High-ROI wins | `AGENTS.md` (vendor-neutral SSoT), `CLAUDE.md`, `CONTRIBUTING.md`, `.claude/settings.json`, permission gates, `.cursorrules`, CI workflow | +| Phase 2 — Contract clarity | Architecture docs, runbooks, ADRs, prompt library, repo-aware helper agents, bundled `review-governor`, release process docs and `/release` skill | +| Phase 3 & 4 — Structure + automation | Triage-first structural cleanup and CI hygiene (do-now / offer / defer) | + +The bundled `review-governor` agent (18 reviewer lenses, 3-phase orchestration) is copied into +the target repo during Phase 2 — no separate install required. + +**Complements `ensure-agents-md`:** `ensure-agents-md` is a lightweight bootstrap that creates +`AGENTS.md` from a fixed AEM template and then immediately continues with the user's request. +`agentify` is the full transformation for repos that need sustained multi-agent AI-native +development. + +```bash +/plugin install aem-agentify@adobe-skills +``` + +See [`plugins/aem/agentify/skills/agentify/`](plugins/aem/agentify/skills/agentify/) for the +skill, phase instructions, AEM conventions, and the bundled `review-governor` distribution. + ### AEM Workflow Workflow skills cover the full AEM Granite Workflow Engine lifecycle — from designing and implementing workflows to production debugging and incident triaging. Like Dispatcher, they are split by runtime flavor: @@ -381,35 +410,46 @@ plugins/ │ │ ├── performance-tuning/ │ │ ├── security-hardening/ │ │ └── workflow-orchestrator/ -│ └── 6.5-lts/ +│ ├── 6.5-lts/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ └── skills/ +│ │ ├── aem-workflow/ +│ │ │ ├── SKILL.md +│ │ │ ├── workflow-model-design/ +│ │ │ ├── workflow-development/ +│ │ │ ├── workflow-triggering/ +│ │ │ ├── workflow-launchers/ +│ │ │ ├── workflow-debugging/ +│ │ │ ├── workflow-triaging/ +│ │ │ └── workflow-orchestrator/ +│ │ ├── aem-replication/ +│ │ │ ├── README.md +│ │ │ ├── SKILL.md +│ │ │ ├── configure-replication-agent/ +│ │ │ ├── replicate-content/ +│ │ │ ├── replication-api/ +│ │ │ └── troubleshoot-replication/ +│ │ ├── ensure-agents-md/ +│ │ └── dispatcher/ +│ │ ├── SKILL.md +│ │ ├── config-authoring/ +│ │ ├── technical-advisory/ +│ │ ├── incident-response/ +│ │ ├── performance-tuning/ +│ │ ├── security-hardening/ +│ │ └── workflow-orchestrator/ +│ └── agentify/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── skills/ -│ ├── aem-workflow/ -│ │ ├── SKILL.md -│ │ ├── workflow-model-design/ -│ │ ├── workflow-development/ -│ │ ├── workflow-triggering/ -│ │ ├── workflow-launchers/ -│ │ ├── workflow-debugging/ -│ │ ├── workflow-triaging/ -│ │ └── workflow-orchestrator/ -│ ├── aem-replication/ -│ │ ├── README.md -│ │ ├── SKILL.md -│ │ ├── configure-replication-agent/ -│ │ ├── replicate-content/ -│ │ ├── replication-api/ -│ │ └── troubleshoot-replication/ -│ ├── ensure-agents-md/ -│ └── dispatcher/ +│ └── agentify/ +│ ├── README.md │ ├── SKILL.md -│ ├── config-authoring/ -│ ├── technical-advisory/ -│ ├── incident-response/ -│ ├── performance-tuning/ -│ ├── security-hardening/ -│ └── workflow-orchestrator/ +│ ├── PLAN.md +│ ├── CONVENTIONS.md +│ ├── references/ +│ └── review-governor/ ├── app-builder/ │ ├── .claude-plugin/ │ │ └── plugin.json diff --git a/plugins/aem/agentify/skills/agentify/CONVENTIONS.md b/plugins/aem/agentify/skills/agentify/CONVENTIONS.md new file mode 100644 index 00000000..726cf087 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/CONVENTIONS.md @@ -0,0 +1,536 @@ +## Appendix A: Conventions to Embed in AGENTS.md + +When creating `AGENTS.md` for a repo, include the sections below that match the repo's +type. These conventions travel with the repo so every AI agent — regardless of which +global rules it has loaded — follows the same standards. + +**Code Standards Scope Rule (strictly enforced for all sections below):** +Apply standards **only to new code**. Never refactor, reformat, or rename pre-existing code +to align with these standards. When adding methods to an existing file, apply standards to +the new methods only; leave everything else untouched. + +--- + +### A.0 — General Coding Principles (All Repo Types) + +Include this section in every AGENTS.md. + +#### Before Writing Code + +- Inspect the repository structure before editing; read any active `AGENTS.md` files. +- Search for existing logic before implementing — avoid duplicating what's already there. +- Keep changes minimal and directly related to the current request. +- **For existing classes: match the existing file's code style, import style, and naming conventions** — even when they differ from the standards below. The standards below apply to new code only. + +#### Code Style + +- **Comments in English only.** +- **Functional over OOP** — prefer stateless pure functions and data transformations; never mutate input parameters or global state as a side effect. Use classes only for connectors to external systems, service components, or types that enforce non-trivial invariants. +- **DRY / KISS / YAGNI** — don't repeat yourself; keep it simple; don't build for hypothetical future needs. +- **Single-purpose functions** — one function does one thing. No flag/mode parameters that switch behavior. +- **Prefer the strongest typing available** — use explicit return types, typed variables, and typed collections in statically typed languages. In dynamically typed languages, add type hints/annotations where supported. Avoid overly broad types (`any`, `Object`, raw generics). +- **Define types for complex structures** — create a named type/record/dataclass instead of passing `Map` or `dict`. + +#### Error Handling + +- Always raise/throw explicitly — never silently ignore errors. +- Use specific error types that clearly indicate what went wrong. +- Error messages must be actionable and include enough context to debug while protecting secrets/PII. Prefer logging non-sensitive identifiers (IDs, correlation IDs), status codes, and high-level summaries. If input or response data must be logged, redact/sanitize sensitive fields and avoid logging full request/response bodies by default (e.g., log truncated/hashed payloads, with explicit opt-in for full content in secure debugging environments). +- **No fallbacks unless explicitly requested.** Fix root causes, not symptoms. +- Use structured/parameterized logging — never interpolate dynamic values into the message string. + +#### Documentation + +- **Code is the primary documentation** — clear naming, types, and docstrings take precedence over prose files. +- Keep documentation co-located with the code it describes. +- **Never duplicate documentation across files** — one authoritative source. + +#### Tooling + +- Run the project's existing tests or validation commands after making changes. +- Use non-interactive command flags so nothing blocks on stdin (e.g. `--no-pager`, `-y`, `--batch`). + +--- + +### A.1 — Git Workflow (All Repo Types) + +Include this section in every AGENTS.md. + +#### Commit Messages + +Format: `WORK-ID : brief description` + +- One line only (most commits) +- Present tense, lowercase, under 72 characters +- No `Co-Authored-By` lines + +``` +PROJ-123 : fix arithmetic expressions with set -e +GH-123 : add null check in content repository service +``` + +#### Staging Files + +**Never use `git add .` or `git add -A`** — these stage untracked files and can +accidentally include secrets (`.env`), personal IDE state, or build artifacts. + +```bash +# Stage specific files (preferred) +git add path/to/File.java + +# Stage only tracked modified files (safe fallback) +git add -u + +# WRONG — never do this +git add . +git add -A +``` + +Always show the user what will be staged/committed/pushed and wait for explicit approval +before running git operations. + +#### Pre-Commit Checklist + +Before every commit: +1. Run the project formatter (e.g. `mvn spotless:apply`, `npm run format`, `black .`) +2. Run tests (`mvn test`, `npm test`, `pytest`) +3. Check status: `git status` +4. Review staged diff: `git diff --staged` + +#### Branch Creation + +Always fetch before creating a branch to ensure it starts from the latest code. +Use `upstream` remote if it exists, otherwise `origin`. +Detect main branch: prefer `trunk` → `main` → `master`. + +```bash +# Fetch first +git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" +git fetch "$remote" + +# Create from latest trunk/main/master +git checkout -b WORK-ID "$remote/trunk" # Apache projects +git checkout -b WORK-ID "$remote/main" # GitHub projects +git checkout -b WORK-ID "$remote/master" # legacy repos using master + +# Verify +git branch -vv +``` + +#### Checking Out an Existing Branch + +Do not just run `git checkout X`. Always stash + checkout + rebase: + +```bash +if git branch --list BRANCH-NAME | grep -q .; then + # Exists locally + git diff --quiet && git diff --cached --quiet || { git stash; STASHED=1; } + git checkout BRANCH-NAME + git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" + git fetch "$remote" + git rebase "$remote/$BASE_BRANCH" + [ "${STASHED:-}" = "1" ] && git stash pop +else + # Does NOT exist locally + git diff --quiet && git diff --cached --quiet || { git stash; STASHED=1; } + git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" + git fetch "$remote" + git checkout -b BRANCH-NAME "${remote}/$BASE_BRANCH" + [ "${STASHED:-}" = "1" ] && git stash pop +fi +``` + +#### Syncing / Rebasing the Current Branch + +```bash +git diff --quiet && git diff --cached --quiet || { git stash; STASHED=1; } +git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" +git fetch "$remote" +git rebase "$remote/$BASE_BRANCH" +[ "${STASHED:-}" = "1" ] && git stash pop +``` + +#### Pull Requests + +Before creating a PR, verify `gh` is configured for the repo's host. Do this **early** +(before writing any files) so a missing account is caught before all work is done. + +```bash +git remote get-url origin # identify the host +gh auth status # list configured accounts — stop if no account matches the host +``` + +If no account is configured for the host, tell the user and stop: +> "`gh` has no account configured for ``. Run `gh auth login` first, then restart." + +Follow the **Pre-PR Verification Gate** in `PLAN.md` before creating any PR. + +Then create the PR: + +```bash +# 1. Switch to the gh account that corresponds to this repo's host +gh auth switch --user YOUR_ACCOUNT_FOR_THIS_HOST + +# 2. Check if a PR already exists — only create if it does not +gh pr view 2>/dev/null && echo "PR exists, skipping" || gh pr create \ + --title "WORK-ID : brief description" \ + --base "$BASE_BRANCH" \ + --assignee @me \ + --body "$(cat <<'EOF' +## Summary + + + +## Changes + + + +## Test Plan + +- [ ] New tests added and passing +- [ ] Existing tests still pass +EOF +)" +``` + +- Always add yourself as assignee: `--assignee @me` +- **Only for repos on github.com with Copilot Enterprise/Business**: add `--reviewer @Copilot` + to `gh pr create`. If it fails, add Copilot via the API after PR creation: + ```bash + PR_NUMBER=$(gh pr view --json number --jq '.number') + gh api repos/OWNER/REPO/pulls/$PR_NUMBER/requested_reviewers \ + -X POST -f 'reviewers[]=github-copilot' + ``` +- **Do not write cross-platform caveats into AGENTS.md.** The distinction above is a + skill-level instruction only — AGENTS.md written into a repo must contain only the rules + that apply to that repo, with no mention of other hosting platforms or repo types. + +#### Merging + +Always squash-merge and delete the branch: + +```bash +gh pr merge --squash --delete-branch --repo OWNER/REPO +``` + +Never use regular merge or rebase merge unless the user explicitly requests it. + +#### Force Push + +Never force push unless a normal `git push origin BRANCH-NAME` fails first. Only use +`--force` as a last resort (e.g. after an unavoidable amend on an already-pushed commit). + +--- + +### A.2 — Java Code Style (Source repos with Java) + +Include this section in AGENTS.md for any repo with `.java` source files. + +#### Imports (new code only) + +- **No static imports** — call static methods via the class name: `Assert.assertEquals()`, `Mockito.when()` +- **No wildcard imports** — explicit only: `import java.util.List;` not `import java.util.*;` +- **No inline fully-qualified package names** — always import and use the simple type name +- **Exception: existing files** — match the file's existing import style exactly. Never add new static imports to an existing file just to satisfy this rule. + +#### Naming Conventions + +```java +public class MyClass { } // Classes: PascalCase +public interface MyInterface { } // Interfaces: PascalCase +public void doSomething() { } // Methods: camelCase +private String myVariable; // Variables: camelCase +public static final String CONSTANT; // Constants: UPPER_SNAKE_CASE +``` + +#### Javadoc (Mandatory for All New Public Methods) + +Every new public method requires Javadoc covering: what it does, each parameter, return +value, and exceptions thrown. + +```java +/** + * Validates and processes a migration state transition. + * + * @param currentState the current migration state (must not be null) + * @param targetState the desired target state (must not be null) + * @return the updated migration state after successful transition + * @throws IllegalArgumentException if either state is null + * @throws IllegalStateException if the transition is not allowed + */ +public MigrationState processTransition(MigrationState currentState, MigrationState targetState) { } +``` + +Private methods: Javadoc optional for obvious methods; required for complex logic. + +#### Parameter Validation (Mandatory for All New Public Methods) + +```java +public void execute(String id, int timeout) { + if (id == null || id.isEmpty()) { + throw new IllegalArgumentException("id cannot be null or empty"); + } + if (timeout <= 0) { + throw new IllegalArgumentException("timeout must be greater than 0"); + } +} +``` + +#### Logging + +```java +private static final Logger log = LoggerFactory.getLogger(MyClass.class); +log.info("Processing item: {}", itemId); // parameterised — never string concatenation +log.error("Operation failed", exception); +``` + +#### Inline Comments + +Use only for non-obvious logic. Do not comment self-explanatory code. + +```java +// Sort descending so highest-priority items are processed first (PROJ-1234) +items.sort(Comparator.comparing(Item::getPriority).reversed()); +``` + +#### Class Structure Order + +1. Static constants +2. Static fields +3. Instance fields +4. Constructors +5. Public methods +6. Package-private methods +7. Private methods +8. Inner classes + +#### Design Principles + +- OSGi components and domain types that enforce invariants are valid class use-cases alongside external-system connectors. +- No flag parameters that switch method behavior: + +```java +// ✅ prefer — two clear methods +public NodeState loadNode(String path) { ... } +public NodeState loadNodeWithCache(String path) { ... } + +// ❌ avoid — flag parameter changes what the function does +public NodeState loadNode(String path, boolean useCache) { ... } +``` + +#### Error Handling (Java-specific) + +See §A.0 for the general error handling principles. Additionally for Java: + +- Prefer `IllegalArgumentException`, `IllegalStateException`, or a domain-specific exception over generic `RuntimeException` +- Catch-all `catch (Exception e)` is only acceptable if you re-throw or wrap with context + +```java +// ✅ specific type, context in message +throw new IllegalArgumentException( + "Cache weight must be positive, got: " + weight + " for key: " + key); + +// ❌ generic, no context +throw new RuntimeException("invalid weight"); + +// ❌ silent swallow +try { ... } catch (Exception e) { log.warn("failed"); } +``` + +#### Java 17 Features (Prefer Over Older Patterns) + +Use modern language features for **new code only**. Do not rewrite existing code. + +**Records** — use for immutable data carriers: +```java +// ✅ prefer +public record CacheEntry(String key, long weight, Instant createdAt) { } +``` + +**Sealed classes** — when the set of subtypes is fixed: +```java +public sealed interface CacheEvent permits HitEvent, MissEvent, EvictionEvent { } +public record HitEvent(String key) implements CacheEvent { } +``` + +**Pattern matching** — eliminate redundant casts: +```java +if (value instanceof String s && !s.isEmpty()) { ... } +``` + +**Text blocks** — for multi-line strings (SQL, JSON, log templates): +```java +String query = """ + SELECT id, name + FROM nodes + WHERE path = ? + """; +``` + +**Switch expressions** — when switching to produce a value: +```java +String label = switch (cause) { + case EXPLICIT -> "invalidated"; + case SIZE -> "evicted"; + case EXPIRED -> "expired"; + default -> "removed"; +}; +``` + +**`var`** — for local variables where the type is obvious from context: +```java +var stats = cache.stats(); // ✅ type clear from right-hand side +var x = compute(); // ❌ type not obvious — use explicit type +``` + +--- + +### A.3 — Java Testing (Source repos with Java + Has-tests) + +Include this section in AGENTS.md for any Java repo with tests (or where tests will be added). + +#### Framework + +- **Use the repo's existing test framework.** If tests already exist, match their framework version — do not introduce a new one without explicit user sign-off. +- **Default for new Java repos with no existing tests:** JUnit 4. If the repo is already on JUnit 5/Jupiter, use JUnit 5. +- Test class names: `MyClassTest` suffix +- Test method names: camelCase — never snake_case +- Test location: mirror source path under `src/test/java/` + +#### Existing Test Files Rule + +Read the file's imports first and match its style exactly — never add new static imports to comply with the no-static-imports standard. + +#### New Test Classes + +No static imports. No wildcard imports. Fully qualified names only. + +```java +import org.junit.Before; +import org.junit.Test; +import org.junit.Assert; +import org.mockito.Mockito; + +public class MyClassTest { + + private MyClass instance; + + @Before + public void setUp() { + instance = new MyClass(); + } + + @Test + public void methodNameWhenConditionExpectsResult() { + String result = instance.doSomething("input"); + Assert.assertEquals("expected", result); + } + + @Test(expected = IllegalArgumentException.class) + public void methodNameThrowsOnNullInput() { + instance.doSomething(null); + } +} +``` + +#### Mockito Patterns (new test classes) + +```java +MyDependency dep = Mockito.mock(MyDependency.class); +Mockito.when(dep.getValue()).thenReturn("value"); +Mockito.when(dep.getValue()).thenThrow(new RuntimeException()); + +Mockito.verify(dep).getValue(); +Mockito.verify(dep, Mockito.times(2)).getValue(); +Mockito.verify(dep, Mockito.never()).getValue(); + +Mockito.when(dep.method(Mockito.anyString())).thenReturn("result"); +``` + +#### Policy + +- Always create unit tests when adding new methods +- **Prefer real objects over mocks** — use Mockito only for external dependencies (file + system, network, databases) +- Cover: success case, exception cases, edge cases, every branch +- **Minimum 90% line/branch coverage** for all new code — Sonar will fail the build below this +- Test method names must encode: what is tested, under what condition, expected outcome + - Good: `transferWhenInsufficientFundsThrowsOverdraftException` + - Bad: `testTransfer`, `test2` + +#### Running Tests + +```bash +mvn test # all tests +mvn test -Dtest=MyClassTest # specific class +mvn test -Dtest=MyClassTest#testName # specific method +``` + +--- + +### A.4 — Bash Style (Infra repos and Source repos with shell scripts) + +Include this section in AGENTS.md for any repo containing `.sh` scripts or shell-heavy +Makefiles / CI scripts. + +#### Function Naming (Strictly Enforced) + +Functions must use **lowercase with underscores**. Never leading underscore, camelCase, or +PascalCase. + +```bash +function validate_migration_state { } # ✅ correct +function _validate_migration_state { } # ❌ leading underscore +function validateMigrationState { } # ❌ camelCase +``` + +Start with action verbs: `execute_`, `verify_`, `validate_`, `assert_`, `check_`. + +#### Arithmetic with `set -e` (Critical) + +`((var++))` exits the script when `var` is 0, killing the process silently. +Always use assignment form instead: + +```bash +retry=$((retry + 1)) # ✅ safe with set -e +((retry++)) # ❌ exits when retry=0 +``` + +Safe exceptions: `if ((count % 10 == 0))`, `local x=$((var++))`, `((VAR++)) || true` + +#### Function Definition Format + +```bash +# +# Brief description of what the function does. +# Parameters: $1 - description of first argument +# Returns: exit code or description of output +# +function my_function_name { + local param1="$1" + # implementation + return 0 +} +``` + +#### Variable Naming + +```bash +local migration_state="$1" # local variables: lowercase_underscores +local MAX_RETRY="${MAX_RETRY:-3}" # constants / env vars: UPPER_UNDERSCORES +``` + +#### Best Practices + +```bash +# Always quote variables +if [ "$variable" == "value" ]; then + echo "Value: ${variable}" +fi + +# Capture exit codes safely around commands that may fail +set +e; some_command; local rc=$?; set -e +[ "$rc" != "0" ] && { echo "ERROR: command failed: $rc"; exit "$rc"; } +``` + +--- diff --git a/plugins/aem/agentify/skills/agentify/PLAN.md b/plugins/aem/agentify/skills/agentify/PLAN.md new file mode 100644 index 00000000..1d9c4385 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/PLAN.md @@ -0,0 +1,490 @@ +# AI-Native Repository Conversion Plan + +A generic, phased, technology-agnostic plan for converting any existing repository into one that LLMs can reason about effectively. + +--- + +## How to Use This Plan + +1. **Run Phase 0** — assess the repo's current state and classify its type. +2. **For each step in Phases 1–4**, read the "When to apply" criterion to decide if it is relevant. +3. **Re-assess quarterly** using Phase 0 to track progress. + +### Non-Negotiable Rules + +See **`SKILL.md` § GLOBAL RULES** — those rules govern all execution and are the single authoritative source. This plan does not repeat them. + +--- + +## Setup and Bootstrap + +**Goal:** Make the skill available in the current session and resolve the supporting files before any repo work begins. + +### Installation Options + +This skill lives in: `https://github.com/adobe/skills` (plugin path: `plugins/aem/agentify/skills/agentify/`) + +Choose one: + +**Option 1 — Plugin marketplace** (recommended): +```bash +/plugin marketplace add adobe/skills +/plugin install aem-agentify@adobe-skills +``` +When installed this way, `SKILL_DIR=${CLAUDE_SKILL_DIR}` — skip the Resolve SKILL_DIR step below. + +**Option 2 — Global symlink** (for development or direct use): +```bash +ln -s ~/path/to/skills/plugins/aem/agentify/skills/agentify \ + ~/.agents/skills/agentify +``` + +Use the tool-native global path for the tool the user selected in Step 0.g: +- Codex → `~/.agents/skills/agentify` +- Claude Code → `~/.claude/skills/agentify` +- Cursor → `~/.cursor/skills/agentify` + +**Option 3 — Run from skills repo** (recommended for remote repos): +```bash +cd ~/path/to/skills +``` +Then launch the selected tool from that directory. + +**Option 4 — Add as extra context dir**: +```bash + --add-dir ~/path/to/skills/plugins/aem/agentify +``` +Use the actual command for the selected tool. If the selected tool does not support `--add-dir` or an equivalent feature, skip this option. + +### Resolve `SKILL_DIR` + +**Plugin marketplace install:** `SKILL_DIR=${CLAUDE_SKILL_DIR}` — already resolved. Skip below. + +**Manual install:** find the skill folder: + +```bash +# Option 2: globally installed for Codex +ls ~/.agents/skills/agentify/PLAN.md 2>/dev/null \ + && echo "SKILL_DIR=~/.agents/skills/agentify" || true + +# Option 2: globally installed for Claude Code +ls ~/.claude/skills/agentify/PLAN.md 2>/dev/null \ + && echo "SKILL_DIR=~/.claude/skills/agentify" || true + +# Option 2: globally installed for Cursor +ls ~/.cursor/skills/agentify/PLAN.md 2>/dev/null \ + && echo "SKILL_DIR=~/.cursor/skills/agentify" || true + +# Option 3/4: project-local (cwd is the skills repo) +repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" && \ + ls "$repo_root/plugins/aem/agentify/skills/agentify/PLAN.md" 2>/dev/null && \ + echo "SKILL_DIR=$repo_root/plugins/aem/agentify/skills/agentify" || true +``` + +Record `SKILL_DIR`. If unresolved, tell the user to install via one of the options above and stop. + +--- + +## Step 0 Execution + +**Goal:** Resolve runtime context for this invocation before Phase 0 assessment begins. + +### 0.a — Detect Execution Mode + +```bash +git rev-parse --show-toplevel 2>/dev/null && echo "IN_REPO" || echo "NOT_IN_REPO" +``` + +| Mode | Condition | Action | +|------|-----------|--------| +| **Local** | Already inside a git repo AND no URL provided | Work in current directory | +| **Remote** | URL provided OR not inside a git repo | Clone first (see 0.b) | + +### 0.b — Remote Mode: Clone the Repo + +1. Ask user where to clone (`~/ai-native/` or custom path). +2. Before cloning, check the target path: + ```bash + ls -la 2>/dev/null && echo "EXISTS" || echo "EMPTY" + ``` +3. If the path exists, ask whether to reuse it, pick a new path, or replace it. +4. Record `ORIGINAL_DIR=$(pwd)` before cloning. +5. Clone and enter the repo: + ```bash + git clone + cd + ``` +6. Record `IS_REMOTE_CLONE=true`. + +### 0.c — Resolve Working Directory Strategy (Remote Mode Only) + +Because the skill is running outside the target repo, every Bash command would otherwise need a `cd ` prefix. Offer the user three options after Step 0.g has identified which tools are being configured: + +> **This skill is running outside the target repo. Choose how to handle the working directory:** +> +> - **A) Global symlink** — Create the tool-native global symlink for the selected tool (`~/.agents/skills/agentify`, `~/.claude/skills/agentify`, or `~/.cursor/skills/agentify`) so the user can open a fresh session in the target repo and the skill will be available there. +> - **B) Tool-native discovery** — Open a new session from the target repo and use the selected tool's normal project or marketplace discovery flow, if it has one. +> - **C) Continue as-is** — Prefix every subsequent Bash command with `cd &&`. + +**For option A:** create the symlink that matches the selected tool: +```bash +# Codex +ln -s ~/.agents/skills/agentify + +# Claude Code +ln -s ~/.claude/skills/agentify + +# Cursor +ln -s ~/.cursor/skills/agentify +``` +Then tell the user to open a new terminal from `` and start a fresh session in the selected tool there. Stop here; the work continues in that new session. + +**For option B:** tell the user to open a new terminal, `cd `, then launch the selected tool and use its normal discovery path (for example, marketplace or project-local skill discovery). Stop here; the work continues in that new session. + +**For option C:** record `WD_STRATEGY=prefix` and continue. All later Bash commands in this skill must be prefixed with `cd &&`. + +### 0.d — Resolve Work Item / Branch Identifier + +```bash +git branch --show-current +git remote get-url origin +``` + +- If the user already provided a work item or branch identifier and the current branch matches, confirm and proceed. +- If the user provided one but the current branch does not match, ask whether to: + - check out or create a branch from that identifier, or + - stay on the current branch and use the identifier only for commit/PR naming. +- If the user did not provide one: + - on `main`/`trunk`/`master`, ask for a short work item or branch identifier; + - otherwise propose the current branch name and wait for confirmation. + +Accept JIRA-style identifiers (`PROJ-12345`), GitHub-style issue keys (`GH-123`), team-specific identifiers, or a plain branch slug. + +Record the confirmed value as `WORK_ID`. Do not continue until `WORK_ID` is confirmed. + +### 0.e — Confirm Base Branches and Branch Naming + +Run both commands to surface all candidate base branches — repos may use non-standard names +like `1.6`, `1.60`, `release/2.x`, `develop`, or `v3`: + +```bash +# 1. All remote branches — shows everything including version-style names +git branch -r | sed 's|origin/||' | sort + +# 2. If the current branch already exists locally, check what remote it tracks +# — this is the authoritative source when the branch was pre-created for you +git remote show origin | grep "merges with remote" +``` + +Do NOT rely solely on the system-provided "main branch" label — it reflects the GitHub +default branch, which may differ from the correct PR target for the current work. + +Ask which branch is the base. Also ask whether the same changes should apply to multiple base branches. + +If the answer is **yes**, create one derived branch per base branch using: +- Single base branch: `BRANCH_NAME="$WORK_ID"` +- Multiple base branches: `BRANCH_NAME="$WORK_ID-$BASE_BRANCH"` (example: `WORK-1234-main`) + +Run the branch/PR flow separately for each entry in `BASE_BRANCHES`. + +Record `BASE_BRANCHES`, whether `MULTI_BASE=yes` or `MULTI_BASE=no`, and the derived `BRANCH_NAME` rule. + +### 0.f — Branch Checkout Rules + +For the current base branch: + +```bash +# Resolve branch name for this base branch +if [ "$MULTI_BASE" = "yes" ]; then + BRANCH_NAME="$WORK_ID-$BASE_BRANCH" +else + BRANCH_NAME="$WORK_ID" +fi + +if git branch --list "$BRANCH_NAME" | grep -q .; then + # EXISTS locally — checkout + rebase + git diff --quiet && git diff --cached --quiet || { git stash; STASHED=1; } + git checkout "$BRANCH_NAME" + git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" + git fetch "$remote" && git rebase "$remote/$BASE_BRANCH" + [ "${STASHED:-}" = "1" ] && git stash pop +else + # Does NOT exist locally — create from base + git diff --quiet && git diff --cached --quiet || { git stash; STASHED=1; } + git remote | grep -q "^upstream$" && remote="upstream" || remote="origin" + git fetch "$remote" + git checkout -b "$BRANCH_NAME" "${remote}/$BASE_BRANCH" + [ "${STASHED:-}" = "1" ] && git stash pop +fi +``` + +### 0.g — Select AI Tools to Support + +Ask which tools to configure (default all selected): + +- **Claude Code** → `CLAUDE.md`, `.claude/settings.json`, `.claude/rules/*.md` +- **GitHub Copilot (IDE)** → `.github/copilot-instructions.md` +- **Cursor** → `.cursorrules`, `.cursor/rules/*.mdc` +- **OpenAI Codex / Gemini / Windsurf** → `AGENTS.md` + +`AGENTS.md` and `.github/CODEOWNERS` are always created regardless of selection. Create +`.cursorrules` when Cursor is selected. + +This Step 0.g list is only the tool-selection summary. The per-section Phase 1 steps below remain +the source of truth for exactly what gets created for each selected tool. + +Record tool selection for the Phase 1 gates. + +--- + +## Repo Type Reference + +The "When to apply" sections use these labels. A repo may match more than one. + +| Label | What it means | +|-------|---------------| +| **Source** | Has `src/` with compilable application code (Java, Python, Go, JS/TS, etc.) | +| **Packaging** | Build file exists but no meaningful source — assembles/bundles external dependencies | +| **Infra** | Contains Dockerfiles, Terraform, Helm, Ansible, shell scripts, k8s manifests | +| **Multi-module** | One logical project with a root build and many submodules (for example Maven/Gradle reactor builds such as `apache/jackrabbit-oak`) | +| **Monorepo** | Multiple relatively independent applications/libraries/tools in one repo, often with separate build/test/deploy flows | +| **Docs** | Contains only documentation, wikis, or specs — no runnable code | +| **LLM-app** | Imports `openai`, `anthropic`, `langchain`, etc.; stores prompts; runs model evaluations | +| **Service** | Exposes a network API (REST, gRPC, GraphQL, message queue) consumed by other systems | +| **Has-tests** | At least one test file exists in the repo | +| **Has-env-vars** | Requires environment variables to build, run, or test | +| **Multi-agent** | Team uses more than one AI coding tool (Claude Code + Copilot, Cursor + Devin, etc.) | + +--- + +## Phase 0: Assessment (Always Run First) + +**Goal:** Understand the repo's current state and type before taking any action. + +### 0.1 — Classify the Repo + +**What to do:** Apply the Repo Type Reference labels above. A repo may have multiple labels (e.g., a Java microservice is both **Source** and **Service**; an AEM content package repo is **Packaging**; `apache/jackrabbit-oak` is **Source**, **Multi-module**, **Has-tests**, and partially **Service**). + +Run these checks: +```bash +# Detect build system +ls pom.xml build.gradle build.gradle.kts package.json go.mod Makefile setup.py pyproject.toml 2>/dev/null + +# Count source files +find . \( -name "*.java" -o -name "*.py" -o -name "*.ts" -o -name "*.go" -o -name "*.js" \) \ + -not -path "*/target/*" -not -path "*/node_modules/*" | wc -l + +# Check for multi-module root +grep -l "" pom.xml settings.gradle settings.gradle.kts 2>/dev/null || true +grep -R "include(" settings.gradle settings.gradle.kts 2>/dev/null || true + +# Check for infra markers +ls Dockerfile docker-compose.yml terraform/ helm/ ansible/ k8s/ *.tf 2>/dev/null || true + +# Check for LLM usage +grep -r "openai\|anthropic\|langchain\|ollama" \ + --include="*.py" --include="*.ts" --include="*.js" -l 2>/dev/null | head -5 || true + +# Check for tests +find . \( -name "*Test*" -o -name "*Spec*" -o -name "test_*.py" \) \ + -not -path "*/target/*" -not -path "*/node_modules/*" | wc -l + +# Check for env var usage +grep -r "process\.env\|os\.environ\|System\.getenv\|dotenv" \ + --include="*.py" --include="*.ts" --include="*.js" --include="*.java" -l 2>/dev/null | head -5 || true + +# Check what AI-native files already exist +ls AGENTS.md CLAUDE.md CONTRIBUTING.md README.md CHANGELOG.md .editorconfig .env.example 2>/dev/null || true +ls .github/CODEOWNERS .github/copilot-instructions.md .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || true +if [ -d .github/workflows ]; then + echo "WORKFLOWS_DIR_PRESENT" + if ! ls .github/workflows; then + echo "WORKFLOWS_LISTING_FAILED" + fi +else + echo "WORKFLOWS_DIR_ABSENT" +fi +ls .claude/settings.json .claude/rules .cursor/rules .cursorrules 2>/dev/null || true +ls wiki/architecture.md wiki/code-flows.md docs/runbooks.md docs/release-process.md docs/testing.md 2>/dev/null || true +find wiki -maxdepth 1 -name 'code-flow-*.md' 2>/dev/null | sort || true +ls docs/decisions/ 2>/dev/null || true +``` + +**Output:** A list of applicable repo type labels. Keep this list — each step in Phases 1–4 uses it to tell you whether to apply that step. + +**Label assignment rules:** + +| Label | Assign when | +|-------|-------------| +| **Source** | ≥1 source file found (.java, .py, .ts, .go, .js) | +| **Packaging** | Build file exists but 0 source files — assembles/bundles dependencies | +| **Infra** | Dockerfile, *.tf, helm/, ansible/, or k8s/ found | +| **Multi-module** | Root pom.xml with `` or settings.gradle with `include(` | +| **Monorepo** | Multiple top-level app/service directories each with own build file | +| **LLM-app** | openai/anthropic/langchain import found | +| **Has-tests** | ≥1 test file found | +| **Has-env-vars** | env var usage found in source | + +> **Monorepo vs Multi-module:** Do NOT label as Monorepo just because many Maven modules exist. +> One root build + one release train = Multi-module. Monorepo = multiple semi-independent +> products with separate lifecycle boundaries. + +**Classification rule for large Java repos:** Do not label a repo **Monorepo** just because it has many Maven or Gradle modules. If there is one root build, one release train, and shared versioning/dependency management, classify it as **Multi-module** first. Use **Monorepo** only when the repo contains multiple semi-independent products or services with separate lifecycle boundaries. + +### 0.2 — Repository Structure Inventory + +**What to do:** Document in one page: directory layout, build system, test framework, CI/CD pipeline, deployment model. + +**Assessment criterion:** Can a new team member answer: (a) what does this repo build, (b) how to build it, (c) how to test it, (d) how to deploy it — without asking anyone? + +### 0.3 — Naming and Convention Audit + +**What to do:** Sample 10–15 files. Are names self-descriptive? Are abbreviations explained? Are conventions consistent? + +**Assessment criterion:** >70% of sampled files pass: public function names are understandable without reading the body. If not, Phase 3 naming work is needed. + +### 0.4 — Test Coverage Audit + +**What to do:** Run coverage tooling. Record line/branch % per module. List modules with zero tests. + +**Assessment criterion:** Modules with <50% line coverage are "AI-opaque." Zero-test modules are the highest priority gap. + +### 0.5 — Implicit Knowledge Audit + +**What to do:** List every piece of knowledge required to build, test, or deploy that is NOT in the repo (Slack messages, tribal knowledge, undocumented env vars, manual steps). + +**Assessment criterion:** Can the project be built from a clean checkout with one documented command? Each undocumented step is a gap. + +--- + +## Phase 1: Zero-Effort, High-ROI Wins + +Canonical instructions: [references/phase-1.md](references/phase-1.md) — covers the SSoT pattern, sections `1.1`–`1.13`, skipped-files report, and exit gate. Keep it as the only active phase document until the exit gate passes. + +--- + +## Phase 2: Contract Clarity + +Canonical instructions: [references/phase-2.md](references/phase-2.md) — covers registration rules, offer workflow, and sections `2.1`–`2.15`. Start only after Phase 1 exit gate passes; keep it as the only active phase document. + +--- + +## Pre-PR Verification Gate + +Before staging, committing, or creating a PR, run this gate every time without exception. + +**Step 1 — Show the diff:** +```bash +git status +git diff HEAD +git ls-files --others --exclude-standard +git ls-files --others --exclude-standard -z | while IFS= read -r -d '' f; do + git diff --no-index -- /dev/null "$f" || true +done +``` +Show the full output to the user. + +**Step 2 — List every file created or modified** with a one-line summary of what was added. +Include untracked files shown by the commands above. + +**Step 3 — Say the following word for word:** + +> --- +> **Please review the changes listed above before I create the PR.** +> +> These files were created or modified by an AI. AI can make mistakes — content may +> be inaccurate, incomplete, or not reflect how this repo actually works. You know +> this codebase better than I do. +> +> **What to check:** +> - Are the build commands, versions, and branch names correct? +> - Does the branching model and versioning strategy match reality? +> - Is anything described that doesn't exist yet, or missing that does? +> - Are the "What Agents Must Not Do" rules complete and accurate? +> - Is any sensitive or internal information included that should not be public? +> +> You can edit any file directly, or tell me what to change and I will update it. +> Once you are satisfied, say **"proceed"** and I will create the PR. +> --- + +**Step 4 — Wait.** Do not create a PR, do not stage any files, do not proceed until the +user explicitly says to. + +**Step 5 — Re-verify on amendments.** If the user changes any file, re-run the full +verification commands above, show the updated output, and ask for confirmation again. + +**Step 6 — Create the PR** only after explicit user go-ahead, for the exact set of files reviewed. + +--- + +## Completion Report + +After the user confirms and the PR is created, output this structured report: + +``` +## AI-Native Conversion Complete + +### Repo Type +[Labels from Phase 0] + +### Files Created +[List each file created in this session] + +### Files Updated +[List each file updated in this session] + +### Files Skipped (already existed) +[List files that were already adequate] + +### Deferred (boy-scout rule) +[Phase 3 steps to apply when naturally touching those files] + +### Quick Win Still Available +[Any Phase 1/4 quick wins not yet done — e.g. PR template §4.3 if skipped] + +### Recommended Next Action +[Single most impactful next step for this repo] +``` + +--- + +## Post-PR Cleanup (Remote Mode Only) + +Run this section only when `IS_REMOTE_CLONE=true`. + +### 6.1 — Return to original directory + +```bash +cd "$ORIGINAL_DIR" +``` + +### 6.2 — Wait for PR merge + +Show the PR URL and say: + +> "The PR is open at: `` +> Please review it, make any final changes, and merge it when ready. +> Let me know once it is merged." + +Wait. Do not proceed until the user confirms the PR is merged. + +### 6.3 — Ask about clone deletion + +Once merged, ask: + +> "The local clone is at ``. The generated `.claude/settings.json` denies `rm -rf`, +> so if you want to remove this clone, please delete it manually." + +--- + +## Phase 3: Structural Improvements + +Canonical instructions: [references/phase-3.md](references/phase-3.md) — covers triage guidance and sections `3.1`–`3.6`. Start only after Phase 2 is complete. + +--- + +## Phase 4: Automation and Ongoing Hygiene + +Canonical instructions: [references/phase-4.md](references/phase-4.md) — covers triage guidance and sections `4.1`–`4.8`. Start only after Phase 3 triage is complete. + +--- diff --git a/plugins/aem/agentify/skills/agentify/README.md b/plugins/aem/agentify/skills/agentify/README.md new file mode 100644 index 00000000..70f5eaff --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/README.md @@ -0,0 +1,66 @@ +# agentify + +Transforms any AEM customer repository into one that AI agents can navigate and contribute to +independently — without hand-holding. + +Invoke with: `agentify`, `make AI native`, `set up agent files`, `add AGENTS.md / CLAUDE.md`, +or `make this repo agent-ready`. + +Works across all AEM repo types: OSGi bundles, content packages, multi-module Maven projects, +AEM Cloud Service projects, and AEM 6.5 / AMS projects. + +## What it creates + +| Output | Purpose | +|--------|---------| +| `AGENTS.md` | Vendor-neutral SSoT — read by Claude Code, Cursor, Copilot, and Codex | +| `CLAUDE.md` | Claude Code projection of `AGENTS.md` | +| `.claude/settings.json` + `.claude/rules/` | Permission gates and quick-reference rule files | +| `.cursorrules` + `.cursor/rules/` | Cursor projection (when selected) | +| `.github/copilot-instructions.md` | Copilot IDE projection (when selected) | +| `CONTRIBUTING.md` | Behavioural contract for human and AI contributors | +| `wiki/architecture.md` + code-flow pages | Architecture and workflow documentation | +| `docs/runbooks.md`, `docs/decisions/` | Operational runbooks and lightweight ADRs | +| `prompts/` | Repo-aware helper prompts | +| `docs/release-process.md` + `skills/release/` | Release documentation and execution skill | + +## How it runs + +Four phases, always in order — nothing writes without user approval: + +- **Phase 0 — Assess**: classifies the repo (Source, Packaging, Multi-module, etc.) and + inventories existing AI-native files. Always runs first. +- **Phase 1 — High-ROI wins**: creates the files AI tools read first — `AGENTS.md`, `CLAUDE.md`, + `CONTRIBUTING.md`, `.gitignore`, CI workflow. Typically 1–2 hours per repo. +- **Phase 2 — Contract clarity**: architecture docs, runbooks, ADRs, prompt library, and + repo-aware agents. Offer/defer workflow per item. +- **Phase 3 & 4 — Structural improvements + automation**: triage-first (do-now / offer / defer). + Covers centralised config/logging, CI coverage gates, pre-commit hooks, living-document hygiene. + +## Relationship to `ensure-agents-md` + +`ensure-agents-md` is a **lightweight bootstrap** — it creates `AGENTS.md` from a fixed AEM +template when none exists, then immediately continues with the user's original request. `agentify` +is the **full transformation** — a structured multi-phase workflow that creates architecture docs, +ADRs, a prompt library, repo-aware agents, CI workflows, and a `/release` skill. Use +`ensure-agents-md` for a quick start on an AEM Cloud Service project; use `agentify` when setting +up any AEM repo for sustained, multi-agent AI-native development. + +## Supporting files + +| File | Purpose | +|------|---------| +| [`SKILL.md`](SKILL.md) | Entry point and execution map | +| [`PLAN.md`](PLAN.md) | Phase routing, Step 0 execution, pre-PR gate, completion report | +| [`CONVENTIONS.md`](CONVENTIONS.md) | AEM coding conventions embedded in generated `AGENTS.md` (Java/OSGi, Bash, Git) | +| [`references/phase-1.md`](references/phase-1.md) | Phase 1 canonical instructions | +| [`references/phase-2.md`](references/phase-2.md) | Phase 2 canonical instructions | +| [`references/phase-3.md`](references/phase-3.md) | Phase 3 canonical instructions | +| [`references/phase-4.md`](references/phase-4.md) | Phase 4 canonical instructions | +| [`references/repo-type-guidance.md`](references/repo-type-guidance.md) | Packaging, Multi-module, even/odd versioning, and LLM-app guidance | +| [`references/repo-agent-templates.md`](references/repo-agent-templates.md) | Templates and registration rules for repo-local helper agents | +| [`references/prompt-templates.md`](references/prompt-templates.md) | Templates and registration rules for repo-aware prompts | +| [`references/skills-templates.md`](references/skills-templates.md) | Templates and registration rules for repo-local skills | +| [`references/rules-templates.md`](references/rules-templates.md) | Templates for `.claude/rules/` and `.cursor/rules/` projection files | +| [`references/release-skill-template.md`](references/release-skill-template.md) | `/release` skill template for versioned Maven/npm repos | +| [`references/maven-release.md`](references/maven-release.md) | Maven release plugin commands, even/odd versioning, troubleshooting | diff --git a/plugins/aem/agentify/skills/agentify/SKILL.md b/plugins/aem/agentify/skills/agentify/SKILL.md new file mode 100644 index 00000000..de24af64 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/SKILL.md @@ -0,0 +1,303 @@ +--- +name: agentify +description: > + Transforms an existing repository into one that AI agents can navigate and + contribute to independently — without hand-holding. Creates AGENTS.md (the + agent's SSoT), CLAUDE.md, .cursorrules, CONTRIBUTING.md, architecture docs, + runbooks, decision records, repo-aware prompts, a root-level `agents/` + catalog for common code flows, and permission gates. Trigger phrases: + "agentify", "make AI native", "set up agent files", "add AGENTS.md / + CLAUDE.md", "make this repo agent-ready". Works across all repo types: + Source, Packaging, Infra, Multi-module, Monorepo, Docs, LLM-app, Service. +tools: Bash, Read, Edit, Write, Glob, Grep +--- + +# agentify Skill + +Transforms an existing repository into one that AI agents can navigate and contribute +to independently. All content requirements, templates, and phase guidance live in the +supporting files — this file is the execution map. + +## Supporting Files + +| File | Purpose | Load when | +|------|---------|-----------| +| [PLAN.md](PLAN.md) | Conversion index: setup, Step 0 execution, Phase 0, phase routing, Phases 3–4, verification gate, completion report | **Once at startup** — before STEP 0. Keep in context for all steps. | +| [CONVENTIONS.md](CONVENTIONS.md) | Code conventions to embed in AGENTS.md: Git workflow, Java, Bash | **Once at startup** — load alongside `PLAN.md`. Needed for AGENTS.md if repo has Java or Bash source. | +| [references/phase-1.md](references/phase-1.md) | Canonical Phase 1 instructions: SSoT pattern, `1.1`–`1.13`, Phase 1 completion gate | Load when STEP 2 begins. Keep it as the only active phase document until Phase 1 is fully complete. | +| [references/phase-2.md](references/phase-2.md) | Canonical Phase 2 instructions: registration rules, offer flow, `2.1`–`2.15` | Load only after Phase 1 is fully complete, `phase-1.md` is no longer the active phase document, and STEP 3 begins. Keep it as the only active phase document for Phase 2. | +| [references/phase-3.md](references/phase-3.md) | Canonical Phase 3 instructions: structural follow-up guidance, triage, and `3.1`–`3.6` | Load when STEP 4 begins. Keep it as the only active phase document until Phase 3 triage and selected work are fully complete. | +| [references/phase-4.md](references/phase-4.md) | Canonical Phase 4 instructions: automation/hygiene guidance, triage, and `4.1`–`4.8` | Load only after Phase 3 is fully complete, `phase-3.md` is no longer the active phase document, and STEP 5 begins. Keep it as the only active phase document for Phase 4. | +| [references/plan-reference.md](references/plan-reference.md) | Quick-reference matrix, effort table, and priority order | Load only when you need lookup/reference material rather than execution steps. | +| [references/prompt-templates.md](references/prompt-templates.md) | Templates and adaptation rules for repo-aware helper prompts and LLM-app prompt layouts; includes exhaustive `prompts/README.md` guidance | Load when §2.12 `prompts/` is in scope. | +| [references/repo-agent-templates.md](references/repo-agent-templates.md) | Templates and selection rules for repo-aware helper agents stored under the target repo's root `agents/` folder; includes exhaustive `agents/README.md` guidance | Load when §2.12 helper agents are in scope. | +| [references/skills-templates.md](references/skills-templates.md) | Templates and selection rules for repo-local skills stored under the target repo's `skills/` folder; includes exhaustive `skills/README.md` guidance and the Skill Registration Rule | Load when §2.6 (`/release` skill), §2.12, or any phase creates repo-local skills. | +| [references/rules-templates.md](references/rules-templates.md) | Templates and content guidance for tool-local quick-reference rule files: `.claude/rules/`, `.cursor/rules/`, `.github/rules/` | Load when §1.11 (Claude rules), §1.7 (Cursor rules), or Copilot rules are in scope. | +| [references/repo-type-guidance.md](references/repo-type-guidance.md) | Repo-type-specific guidance for Packaging, Multi-module, versioning, and LLM-app repos | Load when Step 2 asks for repo-type-specific AGENTS.md guidance. | +| [references/release-skill-template.md](references/release-skill-template.md) | Template for the `/release` skill created inside the target repo | Load when §2.6 asks you to create the release skill. | +| [references/maven-release.md](references/maven-release.md) | Maven release reference (even/odd, commands, rollback, troubleshooting) copied to target repo | Load alongside release-skill-template.md for Maven repos. | + +--- + +## Setup + +Read **`$SKILL_DIR/PLAN.md` § Setup and Bootstrap** and follow it to: +- choose an installation mode if the skill is not yet available, +- resolve `SKILL_DIR`, and +- stop immediately if setup cannot be completed. + +Do not continue until `SKILL_DIR` is resolved and both supporting files are loaded. + +--- + +## GLOBAL RULES + +1. **Show every file before writing it.** Display proposed content and wait for approval. +2. **Never delete or overwrite existing content.** Only add or extend. Read existing files first + and merge additions into them — never replace or discard without explicit approval. +3. **Deletion requires explicit user confirmation with a reason.** If you believe something + should be removed (a section, a file, a line), stop and ask the user. State clearly: + what you want to remove and exactly why. Only proceed after the user explicitly confirms. + A general "ok" or "proceed" is not confirmation — the user must acknowledge the specific item. +4. **Boy-scout rule.** Improve incrementally. Never batch-rewrite beyond what is requested. +5. **AGENTS.md is the SSoT.** Tool-local files (`CLAUDE.md`, `.cursorrules`, + `.github/copilot-instructions.md`) are projections — they must never become competing + sources of truth. They may include a minimal index table (name, path, when-to-use) for + prompts, agents, skills, and workflows so Claude can act without always loading `AGENTS.md`. + This deliberate duplication is intentional and bounded: only the index rows, never the + exhaustive per-item docs. Whenever `AGENTS.md` entries change, sync the index tables in + the projection files in the same commit. +6. **Never add `.cursor/` to `.gitignore`.** `.cursor/rules/` contains committable shared + rules. +7. **Skip steps that already exist.** If a file is adequate, note it as done and move on. +8. **AGENTS.md is repo-specific — never cross-contaminate.** Write only instructions that + apply to the target repo. Never mention other hosting platforms or repo types in the + AGENTS.md written into a repo. +9. **Generated helper agents must be repo-aware.** Create only agents that automate real, + commonly used repo code flows using the target repo's actual commands, docs, paths, and + vocabulary. Do not generate generic placeholder agents. +10. **`agents/` is canonical for repo-local agents.** Tool-local `agents/` directories are + mirrors only and must point back to the root `agents/` folder. +11. **Follow the repo-agent update order exactly.** When §2.12 is in scope or any helper agent + is created, follow the **Agent Registration Rule** in `references/repo-agent-templates.md` + exactly. That file is the authoritative order. +12. **Follow the prompt update order exactly.** When §2.12 is in scope or the prompt library is + updated, follow the **Prompt Registration Rule** in `references/prompt-templates.md` exactly. + That file is the authoritative order. +13. **Follow the skill update order exactly.** When creating repo-local skills (including + `/release`), follow the **Skill Registration Rule** in `references/skills-templates.md` + exactly. That file is the authoritative order. +14. **Follow the workflow update order exactly.** When Phase 2 changes `.github/workflows/` or + related workflow helpers, do the work in this order: update canonical workflow files under + `.github/workflows/` and any touched helpers under `.github/scripts/`; create or update + `docs/workflows.md` so it covers the full current workflow surface in scope; update + `.github/workflows/README.md` with per-workflow behavior; update `AGENTS.md` with the current + workflow surface and canonical doc locations; then update `docs/runbooks.md` and/or + `wiki/architecture.md` when they already exist or were explicitly approved in Phase 2. +15. **Default to a small agent set.** For repo-local agents under `agents/`, aim for 3-5 + high-value agents by default. This is guidance, not a hard cap — create more when the repo's + workflows clearly justify it. +16. **Default to a small prompt set.** For repo-local prompts under `prompts/`, aim for 3-5 + high-value prompts by default. This is guidance, not a hard cap — create more when the repo's + workflows clearly justify it. +17. **Create focused helper-surface API docs.** When Phase 2 includes repo helper surfaces such + as workflows, skills, rules, prompts, or repo-local agents, create or update focused + contract docs under `docs/` instead of burying those contracts in one generic file. Use these + canonical names when the matching surface exists or is created in the target repo: + `docs/workflows.md`, `docs/skills.md`, `docs/rules.md`, `docs/prompts.md`, + and `docs/agents.md`. Keep `docs/api.md` as the top-level index for those contract docs + rather than the only place where the contracts are described. Each surface doc must describe + the full current surface in scope for the repo section it covers, including both pre-existing + items and items created in the current run, not just the delta from this change. Do not create + companion `api.md` files under `skills/`, `prompts/`, `agents/`, `.github/workflows/`, or any + other non-`docs/` path. +18. **Default to a focused ADR set.** For `docs/decisions/`, aim for 4-5 high-value ADRs by + default. This is guidance, not a hard cap — create more when the repo has materially more + independent decisions that would otherwise remain tribal knowledge. +19. **Use one active phase document at a time.** `references/phase-1.md` is the only active phase + instruction source during STEP 2, `references/phase-2.md` during STEP 3, + `references/phase-3.md` during STEP 4, and `references/phase-4.md` during STEP 5. After each + phase reaches its completion gate or final triage state, stop using that phase file as the + active phase document before loading the next one. + +--- + +## STEP 0 — Resolve Execution Mode, Repo, and Work Item + +Read **`$SKILL_DIR/PLAN.md` § Step 0 Execution** and follow it in order to: +- determine local vs remote execution, +- clone and/or switch into the target repo when required, +- resolve the working-directory strategy, +- confirm `WORK_ID`, +- confirm `BASE_BRANCHES` and branch naming, +- run the branch checkout flow for the current base branch, and +- record the selected AI tools. + +Stop at every explicit confirmation gate in the plan. Do not proceed to STEP 1 until Step 0 is fully resolved. + +--- + +## STEP 1 — Phase 0: Assess the Repo + +Read **`$SKILL_DIR/PLAN.md` § Phase 0** for the full assessment commands and label +assignment rules. + +Run all checks from `PLAN.md` §0.1, collect the results, then output: +- A list of applicable Repo Type Labels +- A one-paragraph summary of the repo's current AI-nativeness state +- The set of Phase 1 steps that are applicable + +**Do not proceed to STEP 2 until the user has confirmed the classification is correct.** + +--- + +## STEP 2 — Phase 1: Zero-Effort High-ROI Files + +Read **`$SKILL_DIR/references/phase-1.md`** for the full Phase 1 requirements and templates for +each file. This is the only active phase document during STEP 2. This step provides only the +execution workflow (tool gates, ordering, approval). + +**For each file in scope:** +1. Check tool selection from Step 0.g — if tool deselected, skip this file entirely +2. Check if file already exists — if yes, read it and decide what needs updating +3. Read `references/phase-1.md` for this file's content requirements and template +4. For AGENTS.md: run the **mandatory codebase exploration** from + **`$SKILL_DIR/references/phase-1.md` §1.6** before + drafting. Also read + **`$SKILL_DIR/CONVENTIONS.md`** for the conventions sections to append (Java style, + Java testing, Bash style) based on repo type labels +5. Draft content tailored to this specific repo — never generic boilerplate +6. Show the draft and wait for approval +7. Write only after approval + +**Path order, tool gates, and `references/phase-1.md` section references:** + +| Path | Tool gate | `references/phase-1.md` section | +|------|-----------|-----------------| +| `AGENTS.md` | Always — first | §1.6 + CONVENTIONS.md Appendix A | +| `CLAUDE.md` | Claude Code selected | §1.1 | +| `.claude/settings.json` | Claude Code selected | §1.11 | +| `.claude/rules/*.md` | Claude Code selected | §1.11 | +| `.cursorrules` | Cursor selected | §1.7 | +| `.cursor/rules/*.mdc` | Cursor selected | §1.7 | +| `README.md` | Always | §1.2 | +| `CONTRIBUTING.md` | Always | §1.3 | +| `.github/CODEOWNERS` | Always (GitHub repos) | §1.4 | +| `.github/copilot-instructions.md` | GitHub Copilot (IDE) selected | §1.5 | +| `.gitignore` | Always | §1.9 | +| `.editorconfig` | All repos with text files | §1.8 | +| `.env.example` | Has-env-vars repos only | §1.10 | +| `.github/workflows/ci.yml` | GitHub repos | §1.12 | +| `.codex/` + `.agents/` | Codex / Gemini / Windsurf / generic tool selected | §1.13 | + +For repo-type-specific AGENTS.md guidance (Packaging, Multi-module, even/odd versioning, +LLM-app): read **`$SKILL_DIR/references/repo-type-guidance.md`**. + +After all files: output the **Skipped-Files Report** (`references/phase-1.md` § Phase 1 Completion), +then confirm the **Phase 1 Exit Gate** in that file is satisfied. Do not move on while any +Phase 1 work is still pending. + +Do not proceed to STEP 3 until the Phase 1 Exit Gate in `references/phase-1.md` is satisfied. + +--- + +## STEP 3 — Phase 2: Contract Clarity + +Read **`$SKILL_DIR/references/phase-2.md`** for content requirements and registration rules for +each deliverable. Follow the offer workflow in +**`$SKILL_DIR/references/phase-2.md` § Presenting Phase 2 to the User**. + +Key rules: +- Do not enter STEP 3 until the **Phase 1 Exit Gate** in `references/phase-1.md` is satisfied and + there is no pending Phase 1 work +- `references/phase-2.md` is self-sufficient for Phase 2. Once STEP 3 begins, it replaces + `references/phase-1.md` as the active phase document +- Always offer Phase 2 after Phase 1 — do not start without asking +- Before drafting any Phase 2 deliverable, explicitly present the applicable Phase 2 items to the user and wait for a yes/no decision on what to do now versus defer +- `docs/release-process.md`, `CHANGELOG.md`, and the `/release` execution skill are **not deferrable** for versioned repos +- Phase 2 may assume that every applicable Phase 1 file already exists in final approved form and + may update those files where the Phase 2 rules require it +- For each deliverable: read source files first, draft from real content, show draft, write after approval +- Never assume the user wants to defer — ask explicitly +- Any edit to `wiki/architecture.md`, `wiki/code-flows.md`, or any `wiki/code-flow-*.md` file must be treated as a two-part change: update the repo copy and sync the GitHub wiki before moving on +- If the current change modifies a workflow, automation path, or code path that already has a matching `wiki/code-flow-*.md` page, update that wiki page in the same change instead of leaving it stale +- In `AGENTS.md`, keep `wiki/code-flows.md` as the workflow-doc entry point in `## Key Documentation`; list `wiki/code-flow-*.md` in the repository structure and let the index page link to the individual workflow docs +- Treat API documentation as four separate concerns during Phase 2: + - service/network API docs (`references/phase-2.md` §2.7) + - public library / consumer contract overview docs (`references/phase-2.md` §2.8 public API surface reference) + - source-level API docs in touched files (`references/phase-2.md` §2.8 boy-scout rule) + - helper-surface contract docs for workflows, skills, rules, prompts, and agents (`references/phase-2.md` §2.12) +- **After writing each Phase 2 deliverable**, apply the **Phase 2 Registration Rule** + (`references/phase-2.md` § Phase 2 Registration Rule) — update `AGENTS.md`'s repo structure + tree and `## Key Documentation` table to reference the new file or prompt entry point + +--- + +## STEP 4 — Phase 3: Structural Improvements + +Read **`$SKILL_DIR/references/phase-3.md`**. + +Summarise which Phase 3 steps are applicable, then classify each applicable step using the +default triage guidance in `references/phase-3.md`. + +For each classified Phase 3 item: +- execute `Do now` items in the current session +- present `Offer now` items to the user and wait for approval before doing them +- record `Defer` items for the completion report + +Do not describe all of Phase 3 as blanket defer work. Keep `references/phase-3.md` as the only +active phase document during this step. Once Phase 3 triage and any selected Phase 3 work are in +final state, stop using `references/phase-3.md` as the active phase document before loading +`references/phase-4.md`. + +--- + +## STEP 5 — Phase 4: Automation and Ongoing Hygiene + +Read **`$SKILL_DIR/references/phase-4.md`**. + +Summarise which Phase 4 steps are applicable, then classify each applicable step using the +default triage guidance in `references/phase-4.md`. + +For each classified Phase 4 item: +- execute `Do now` items in the current session +- present `Offer now` items to the user and wait for approval before doing them +- record `Defer` items for the completion report + +Do not describe all of Phase 4 as blanket defer work. Keep `references/phase-4.md` as the only +active phase document during this step. + +--- + +## STEP 6 — User Verification and Completion Report + +### Review generated files for overlap and redundancy + +Check that no convention, rule, or process is documented in more than one place across the files +created or modified in this session (e.g. the same git workflow in both `AGENTS.md` and +`CONTRIBUTING.md`). Remove duplicates from the new or newly edited content in this run and ensure +each file has a single clear purpose. If fixing duplication would require deleting or replacing +pre-existing repo content outside the sections you already drafted for this session, stop and ask +the user for explicit approval before removing it. + +If using Claude Code, run `/simplify` on the changed files. Other tools: manually diff the generated files against each other and consolidate. + +### Mandatory verification before any PR + +Follow the full gate defined in **`$SKILL_DIR/PLAN.md` § Pre-PR Verification Gate** exactly as written there. Do not abbreviate or skip any step. + +### Completion Report + +Output after the PR is created (template in **`$SKILL_DIR/PLAN.md` § Completion Report**). + +--- + +## STEP 7 — Post-PR Cleanup (Remote mode only) + +If `IS_REMOTE_CLONE` is set, run the full cleanup flow from +**`$SKILL_DIR/PLAN.md` § Post-PR Cleanup (Remote Mode Only)**. +Otherwise skip this step entirely. + +--- + +When any step says "read `PLAN.md` §X", open `$SKILL_DIR/PLAN.md` and navigate to that section. diff --git a/plugins/aem/agentify/skills/agentify/references/maven-release.md b/plugins/aem/agentify/skills/agentify/references/maven-release.md new file mode 100644 index 00000000..9fed8d33 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/maven-release.md @@ -0,0 +1,147 @@ +# Maven Release Reference + +Detailed commands and troubleshooting for Maven releases using the Maven Release Plugin. + +--- + +## Even/Odd Versioning (AEM Maven Convention) + +| Phase | Version pattern | Example | +|-------|----------------|---------| +| Active development | `MAJOR.ODD.PATCH-SNAPSHOT` | `1.3.0-SNAPSHOT` | +| Release | `MAJOR.EVEN.PATCH` | `1.4.0` | +| Next dev cycle | `MAJOR.(ODD+2).PATCH-SNAPSHOT` | `1.5.0-SNAPSHOT` | + +Rules: +- Odd minor = development (`-SNAPSHOT`) +- Even minor = released artifact (no `-SNAPSHOT`) +- Never release with an odd minor version +- Never have a `-SNAPSHOT` on an even minor version + +**Common version progressions:** + +``` +1.3.0-SNAPSHOT → 1.4.0 → 1.5.0-SNAPSHOT +2.1.4-SNAPSHOT → 2.2.4 → 2.3.4-SNAPSHOT +3.7.0-SNAPSHOT → 3.8.0 → 3.9.0-SNAPSHOT +``` + +--- + +## Pre-Release Commands + +```bash +# 1. Verify clean working tree +git status + +# 2. Verify tests pass +mvn verify -B + +# 3. Check for unintended SNAPSHOT deps (exclude own project version) +CURRENT=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout) +SNAPSHOTS=$(mvn dependency:list | grep -F SNAPSHOT | grep -vF "$CURRENT" || true) +if [ -n "$SNAPSHOTS" ]; then + echo "ERROR: Unintended SNAPSHOT dependencies found:" + echo "$SNAPSHOTS" + exit 1 +fi + +# 4. Dry-run: simulate prepare — makes local-only changes (release.properties, backup poms) +# but does NOT commit or push; clean up with: rm -f release.properties pom.xml.releaseBackup +mvn release:prepare --dry-run -B \ + -DreleaseVersion= \ + -DdevelopmentVersion=-SNAPSHOT # is base only, e.g. 1.5.0 +``` + +--- + +## Release Prepare + +Creates the release commit + tag and bumps `pom.xml` to the next SNAPSHOT version. + +```bash +mvn release:prepare -B \ + -DreleaseVersion= \ + -DdevelopmentVersion=-SNAPSHOT # is base only, e.g. 1.5.0 +``` + +What this does: +1. Validates no SNAPSHOT dependencies +2. Changes `pom.xml` version to ``, commits and pushes +3. Tags the commit as `` (default format: `-`; check `` in root `pom.xml` if different) +4. Changes `pom.xml` version to `-SNAPSHOT`, commits and pushes + +**Multi-module note:** All modules are version-bumped in a single commit. Verify tag naming in the root `pom.xml` `` section. + +--- + +## Release Perform + +Checks out the tag, builds from it, and deploys to Nexus / Maven Central. + +```bash +mvn release:perform -B +``` + +--- + +## Full Even/Odd Example + +```bash +# Current: 1.3.0-SNAPSHOT → Release: 1.4.0 → Next dev: 1.5.0-SNAPSHOT + +mvn release:prepare --dry-run -B \ + -DreleaseVersion=1.4.0 \ + -DdevelopmentVersion=1.5.0-SNAPSHOT + +mvn release:prepare -B \ + -DreleaseVersion=1.4.0 \ + -DdevelopmentVersion=1.5.0-SNAPSHOT + +mvn release:perform -B +``` + +--- + +## Rollback + +Use only if `release:perform` has NOT yet deployed the artifact. + +```bash +# Reverts pom.xml changes and deletes the local tag +mvn release:rollback + +# Delete the remote tag if it was pushed +git push origin :refs/tags/ +``` + +If `release:rollback` fails (e.g. `release.properties` is missing): + +```bash +git log --oneline -5 # find the commit before release:prepare started +git reset --hard +git push --force-with-lease origin +git push origin :refs/tags/ +``` + +--- + +## Troubleshooting + +**`SCM operation failed`** — verify SSH keys or HTTPS credentials, and check `` in `pom.xml` matches `git remote -v` + +**`You have local modifications`** — run `git status` and stash or commit the changes + +**Stale `release.properties` from a previous failed run** — `rm release.properties` + +**`Artifact already deployed`** — delete it from Nexus or bump the version + +**`No SCM URL configured`** — add to root `pom.xml`: +```xml + + scm:git:https://github.com/OWNER/REPO.git + scm:git:git@github.com:OWNER/REPO.git + https://github.com/OWNER/REPO + HEAD + +``` diff --git a/plugins/aem/agentify/skills/agentify/references/phase-1.md b/plugins/aem/agentify/skills/agentify/references/phase-1.md new file mode 100644 index 00000000..b395b08f --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/phase-1.md @@ -0,0 +1,551 @@ +# Agentify Phase 1 + +Use this file for the full Phase 1 workflow. `PLAN.md` remains the top-level execution index, +but the canonical Phase 1 instructions live here. This document is self-sufficient for Phase 1: +while it is active, do not load or use `phase-2.md` as an execution source. + +## Scope And Prerequisites + +- Start only after Step 0 is resolved and Phase 0 classification is confirmed. +- Use this file for all `1.1`–`1.13` work and for the Phase 1 completion gate. +- Keep `AGENTS.md` as the single source of truth. Tool-local files stay lightweight projections. +- For applicability, effort, and priority lookup, use [plan-reference.md](plan-reference.md). +- For repo-type-specific Phase 1 guidance, use [repo-type-guidance.md](repo-type-guidance.md). + +## Phase 1: Zero-Effort, High-ROI Wins + +**Goal:** Add the files AI tools read first. No source code changes required. + +### The Single Source Of Truth Pattern + +Use `AGENTS.md` as the single source of truth. It is vendor-neutral and read by OpenAI Codex, +GitHub Copilot Workspace, and future agents. + +Tool-local projection files (`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`) +are lightweight pointers — but they deliberately include one additional element beyond a pure +pointer: a **minimal index table** (name, path, when-to-use) for prompts, agents, skills, and +workflows when those surfaces exist in the repo. This lets Claude act without always loading +`AGENTS.md`. Only the index rows are copied — never the exhaustive per-item docs, which belong +in `prompts/README.md`, `agents/README.md`, `skills/README.md`, and `.github/workflows/README.md`. + +**Rule:** When conventions change, update `AGENTS.md` first. Then sync the index tables in +the projection files in the same commit. All generated projection files must say explicitly that +they are projections and must not be edited directly. + +```text +AGENTS.md ← full conventions, build, architecture, anti-patterns (SSoT) + ↑ referenced by: + ├── CLAUDE.md ← Claude Code + ├── .claude/rules/*.md ← Claude quick-reference rules (when selected) + ├── .cursorrules ← Cursor (when selected) + ├── .cursor/rules/*.mdc ← Cursor quick-reference rules (when selected) + └── .github/copilot-instructions.md ← GitHub Copilot IDE +``` + +If the repo has repo-local helper agents, keep them canonical under the root `agents/` folder. +Tool-local `agents/` paths are mirrors only and must point back to `agents/`: + +```text +agents/ ← canonical repo-aware agent catalog +.claude/agents ← symlink mirror → ../agents +.codex/agents ← symlink mirror → ../agents +.agents/agents ← symlink mirror → ../agents +.cursor/agents ← symlink mirror → ../agents +.github/agents ← symlink mirror → ../agents +``` + +### 1.1 — `CLAUDE.md` + +**When to apply:** Claude Code selected. + +**What to do:** Create `CLAUDE.md` at repo root as a projection of `AGENTS.md`. +Include: +- a prominent "Projection only: never edit this file directly; update `AGENTS.md` first." note +- a "Canonical source: `AGENTS.md`" header +- a "Projected from `AGENTS.md` as of " audit line +- a reminder to update `AGENTS.md` first when repo guidance changes +- a minimal quick-reference summary of critical rules +- if `prompts/` exists: the same minimal index table from `AGENTS.md#prompt-library` (name, path, + when-to-use) plus a pointer to `prompts/README.md` for the exhaustive catalog +- if `agents/` exists: the same minimal index table from `AGENTS.md#available-agents` (name, path, + when-to-use) plus a pointer to `agents/README.md` for the exhaustive catalog +- if `skills/` exists: the same minimal index table from `AGENTS.md#available-skills` (name, path, + when-to-use) plus a pointer to `skills/README.md` for the exhaustive catalog +- if `.github/workflows/` exists: the same minimal index table from `AGENTS.md#workflow-overview` + (name, file, trigger) plus a pointer to `.github/workflows/README.md` for the exhaustive catalog + +**Minimal-index rule for projections:** `CLAUDE.md` must mirror the same minimal index tables +that live in `AGENTS.md` — not copy the exhaustive docs. The table rows (name, path, when-to-use) +are enough for Claude to act without opening `AGENTS.md`. The exhaustive per-item docs belong in +`prompts/README.md`, `agents/README.md`, and `skills/README.md` only. Keep `CLAUDE.md` in sync +with `AGENTS.md` whenever entries are added, renamed, or removed. + +Do not create `.claude/rules/*.md` here. Those belong to `1.11`. + +**Files:** New `CLAUDE.md`. + +**Done when:** An LLM reading this file knows to load `AGENTS.md` and has enough quick context to +avoid common mistakes when `AGENTS.md` is not already in context. + +**Repo type notes:** +- Packaging: focus on dependency management, versioning strategy, release process, and build DSL. +- Infra: document target environment, required access, and deploy/apply workflow. +- Multi-module: include a module map and commonly changed-together modules. +- Monorepo: include a package/app map and per-unit notes for major independently owned areas. +- LLM-app: document model usage, prompt locations, and eval flow. + +### 1.2 — `README.md` + +**When to apply:** All repo types. + +If `README.md` already exists: +- do not delete or replace existing content +- add a short AI Agents section immediately after the first paragraph: + +```markdown +## AI Agents + +This repository is AI-native. See **[AGENTS.md](AGENTS.md)** for the full agent +guide: build/test commands, architecture, what agents may and must not do, git +workflow, and versioning conventions. +``` + +If `README.md` does not exist, create one with at minimum: +- project name and one-sentence description +- the AI Agents section above +- prerequisites +- build command +- test command +- link to deeper documentation + +If a legacy `readme.txt` exists, do not delete it. Note in `README.md` that `readme.txt` exists +and `README.md` is canonical going forward. + +**Files:** `README.md` at repo root. + +**Done when:** A new contributor can clone and build within 15 minutes and immediately knows to +read `AGENTS.md` for AI guidance. + +### 1.3 — `CONTRIBUTING.md` + +**When to apply:** All repo types. + +**What to do:** Create `CONTRIBUTING.md` covering: +- coding conventions +- branch and PR workflow +- testing expectations +- how AI agents should work in the repo +- single source of truth for standard commands: `install`, `dev`, `test`, `lint`, `typecheck`, `build` + +Any `gh pr create` example must include `--body` or `--fill`. + +**Files:** New `CONTRIBUTING.md`. + +**Done when:** An AI agent reading only this file knows the style, PR shape, test expectations, +and hard boundaries. + +### 1.4 — `.github/CODEOWNERS` + +**When to apply:** All GitHub-hosted repos. + +**What to do:** Create or update `.github/CODEOWNERS`. + +**Before writing:** Ask the user for the exact GitHub team or user handle — do not use a +placeholder. If the information is not readily available, pause and ask: +*"What GitHub team or user should own PRs in this repo? (e.g. @MyOrg/my-team)"* + +Minimum content (substitute the real handle): + +```text +# Route all PRs to the team for required human review + automatic Copilot code review. +# Only the last matching rule takes effect in CODEOWNERS — keep all owners on one line. +# Copilot review requires GitHub Copilot Enterprise/Business licence. +# Enable in: GitHub repo Settings → Copilot → Pull request reviews +* @your-org/actual-team-name @Copilot +``` + +Important: +- do not use two separate `*` lines +- if a `*` entry already exists, merge owners onto one line +- `@Copilot` is for review, not autonomous coding + +**Files:** `.github/CODEOWNERS`. + +**Done when:** The file exists with at least the team/owner entry. Copilot review entry may be +added now or later. + +### 1.5 — `.github/copilot-instructions.md` + +**When to apply:** All GitHub-hosted repos. + +**What to do:** Create `.github/copilot-instructions.md` as a projection of `AGENTS.md`. +Include the same projection/audit/reminder pattern used for `CLAUDE.md`, plus a minimal +critical-rules summary. + +Apply the same minimal-index rule as `CLAUDE.md`: for prompts, agents, and skills include only +a single pointer line to `AGENTS.md` and the relevant exhaustive `README.md` — do not list +individual items or copy their docs into this file. + +Do not duplicate the full contents of `AGENTS.md`. + +**Files:** New `.github/copilot-instructions.md`. + +**Done when:** Copilot suggestions in the IDE align with project style without manual correction. + +### 1.6 — `AGENTS.md` + +**When to apply:** All repo types. + +**Before drafting — mandatory codebase exploration:** + +Run these checks and record the findings. `AGENTS.md` must contain real repo facts, not +placeholders. + +```bash +git branch -r | grep -E "prod|develop|release|maintenance" | head -20 +ls docs/ 2>/dev/null +grep -i "release\|maven-scm\|npm version\|git tag" Jenkinsfile .github/workflows/*.yml 2>/dev/null | head -20 +grep -i "sonar\|coverage\|skip\|disable\|comment" Jenkinsfile 2>/dev/null | head -10 +cat index.jsx index.js index.ts 2>/dev/null | head -30 +ls src/*/components/ src/*/supercomponents/ 2>/dev/null | head -30 +cat docs/naming.md docs/webcomponents.md docs/component.md 2>/dev/null | head -80 +``` + +`AGENTS.md` must include: +- library entry point and path aliases when applicable +- branching model +- component naming conventions when present +- release ownership +- disabled CI features that agents must not assume exist +- immutable public API elements +- minimal prompt-library index when `prompts/` exists or will be created (path + one-liner per prompt; exhaustive docs belong in `prompts/README.md`) +- minimal available-agents index when repo-local agents exist or will be created (name + path + one-liner per agent; exhaustive docs belong in `agents/README.md`) +- minimal available-skills index when repo-local skills exist or will be created (name + path + one-liner per skill; exhaustive docs belong in `skills/README.md`) + +**What to do:** Create `AGENTS.md` covering: +- repo type and what agents may/may not do +- build and test commands +- library consumption pattern and path aliases when applicable +- branching model +- component naming conventions +- key files to read first +- project-specific rules +- commit format +- minimal prompt library index with pointer to `prompts/README.md` as exhaustive catalog (when present) +- minimal agent catalog index with pointer to `agents/README.md` as exhaustive catalog (when present) +- minimal skill catalog index with pointer to `skills/README.md` as exhaustive catalog (when present) + +**Minimal-index rule:** `AGENTS.md` is the SSoT for *where* things live and *when to use* them — +not the full documentation for each surface. Keep prompt, agent, and skill entries short (one line +per item). Put exhaustive per-item documentation — full workflow steps, invocation examples, +constraints, file lists — in `prompts/README.md`, `agents/README.md`, and `skills/README.md` +respectively. This keeps `AGENTS.md` scannable and prevents it from becoming a duplicate of those +catalogs. + +Any `gh pr create` example must include `--body` or `--fill`. + +If the target repo contains `SKILL.md` files, document frontmatter with: +- Required: `name`, `description` +- Optional: `argument-hint`, `disable-model-invocation`, `tools` / `allowed-tools` + +**Done when:** An agent reading only `AGENTS.md` knows what the repo does, what it may change, +what it must not do, and how to commit. + +**Conventions — choose inline or split based on repo complexity:** + +Before embedding conventions, ask whether `AGENTS.md` would exceed about 400 lines. If the repo +has 3+ languages or multiple owning teams, offer a split pattern under `docs/conventions/`. + +Inline option: +- all repos: A.0 General Coding + A.1 Git Workflow +- Java source repos: A.2 Java Code Style + A.3 Java Testing when applicable +- shell repos: A.4 Bash Style + +Split option: + +```text +docs/conventions/general.md +docs/conventions/git.md +docs/conventions/java-style.md +docs/conventions/java-testing.md +docs/conventions/bash.md +``` + +Even when split files are used, the following must stay inline in `AGENTS.md`: +- build and test commands +- must-not-do list +- branching model + +If split files are used, also update pointer files to link directly to them. + +For repo-type-specific guidance, use [repo-type-guidance.md](repo-type-guidance.md). + +### 1.7 — `.cursorrules` + +**When to apply:** Cursor selected. + +**Before drafting `.cursor/rules/` files:** Read [rules-templates.md](rules-templates.md) for +content guidance, Cursor `.mdc` front matter format, and which rule files to create. + +**What to do:** Create `.cursorrules` at repo root as a projection of `AGENTS.md`. +Include the projection note, canonical source line, projected-from audit line, sync reminder, +and a minimal quick-reference summary. + +Apply the same minimal-index rule as `CLAUDE.md`: for prompts, agents, and skills include only +a single pointer line per surface to `AGENTS.md` and the relevant exhaustive `README.md` — do +not list individual items or copy their docs into this file. + +Also ensure `.cursor/rules/` exists and create only the applicable `.mdc` rule files: +- `general-coding.mdc` +- `git-practices.mdc` +- `java-style.mdc` +- `java-testing.mdc` +- `bash-style.mdc` +- `skill-authoring.mdc` + +Each `.mdc` file must: +- say it is a projection +- name `AGENTS.md` as canonical source +- include a projected-from audit line +- remind the reader to update `AGENTS.md` first +- stay short and link back to `AGENTS.md` + +Do not mirror full convention blocks into `.cursor/rules/*.mdc`. + +**Files:** New `.cursorrules`; ensure `.cursor/rules/` exists and create applicable `.mdc` files. + +**Done when:** A Cursor agent knows to read `AGENTS.md` and has enough quick guidance to avoid +common mistakes. + +### 1.8 — `.editorconfig` + +**When to apply:** All repos with text files. + +**What to do:** Create `.editorconfig` with the project's actual formatting conventions. + +**Files:** New `.editorconfig`. + +**Done when:** Running the formatter on any file produces no changes. + +### 1.9 — `.gitignore` + +**When to apply:** All repo types. + +**What to do:** Ensure `.gitignore` covers build output, IDE files, OS files, secrets, and +compiled output. Add ecosystem-specific entries as needed. + +If Claude Code was selected, also append: + +```text +# Claude Code local settings (personal overrides, not shared) +.claude/settings.local.json +``` + +Do not add `.cursor/`. + +**Files:** `.gitignore` at repo root. + +**Done when:** A fresh build does not leave untracked IDE, build, or secret files in `git status`. + +### 1.10 — `.env.example` + +**When to apply:** Has-env-vars repos only. + +**What to do:** Create `.env.example` listing every required environment variable with a safe +placeholder and one-line explanation. Ensure `.env` is ignored. + +**Files:** New `.env.example`; update `.gitignore`. + +**Done when:** Every env var needed to run the project is listed. + +**Skip if:** Config lives only in checked-in files. In that case add a note in `CLAUDE.md` +explaining where configuration lives. + +### 1.11 — `.claude/settings.json` + `.claude/rules/` + +**When to apply:** Claude Code selected. + +**Before drafting rule files:** Read [rules-templates.md](rules-templates.md) for content +guidance, projection header format, and which rule files to create based on repo type. + +**What to do:** Create `.claude/settings.json` with permission gates that require approval before +commits, pushes, or branch-changing operations. Also ensure `.claude/rules/` exists and contains +only the applicable Markdown quick-reference files: +- `general-coding.md` +- `git-practices.md` +- `java-style.md` +- `java-testing.md` +- `bash-style.md` +- `skill-authoring.md` + +Note: `skill-authoring.md` applies whenever `skills/` exists **or will be created** (e.g. by +`/release` skill in Phase 2). If Phase 1 runs before Phase 2 creates `skills/`, come back and +add this rule file immediately after `skills/` is first written in Phase 2. + +Each generated Claude rule file must: +- say it is a projection +- start with "Canonical source: `AGENTS.md`" +- include a projected-from audit line +- remind the reader to update `AGENTS.md` first +- stay short and link back to `AGENTS.md` + +Example permission shape: + +```json +{ + "permissions": { + "allow": ["Bash(cp:*)", "Bash(gh auth:*)"], + "ask": [ + "Bash(git stash:*)", + "Bash(git checkout:*)", + "Bash(git add:*)", + "Bash(git push:*)", + "Bash(git commit:*)" + ], + "deny": ["Bash(rm -rf:*)"] + } +} +``` + +**Files:** New `.claude/settings.json`; ensure `.claude/rules/` exists and create applicable +Markdown rule files. + +**Done when:** Claude Code pauses before any git write operation or destructive recursive delete. + +### 1.12 — `.github/workflows/ci.yml` + +**When to apply:** All GitHub-hosted repos. + +**What to do:** +1. Use the Phase 0 `.github/workflows` listing as the source of truth. +2. If workflows exist, read them and propose additive fixes only. +3. If no workflows exist, propose a minimal CI workflow appropriate for the repo type and ask for + explicit confirmation before writing. + +Do not write anything under `.github/workflows/` without stating the exact path, what the +workflow does, and asking for explicit approval. + +Minimal Java/Maven CI: + +```yaml +name: CI + +on: + pull_request: + push: + branches: [main, master, trunk] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-java@v4 + with: + java-version: '17' + distribution: 'temurin' + cache: maven + - name: Build and test + run: mvn --batch-mode verify +``` + +Minimal Node CI: + +```yaml +name: CI + +on: + pull_request: + push: + branches: [main, master, trunk] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: npm + - run: npm ci + - run: npm test +``` + +**Files:** New `.github/workflows/ci.yml` or additive edits to existing workflows. + +**Done when:** PRs trigger automated build and test checks. + +--- + +### 1.13 — `.codex/` and `.agents/` (Codex and generic AI tools) + +**When to apply:** OpenAI Codex, Gemini, Windsurf, or any generic agent tool selected. + +**What to do:** Create the tool-local discovery directories so Codex and other tools can +find repo-local agents (and skills, when present). + +- **`.codex/`** — Codex project-local directory. + - Ensure `.codex/` exists. When neither `agents/` nor `skills/` exists yet, the empty + directory acts as a discovery hook for future additions. + - If `agents/` exists in the repo: create `.codex/agents` as a symlink → `../agents` + (skip if the symlink already exists — use `ln -sfn` or check first) + - If `skills/` exists in the repo: create `.codex/skills` as a symlink → `../skills` + (skip if the symlink already exists) + +- **`.agents/`** — generic agent tool discovery directory. + - Ensure `.agents/` exists. + - If `agents/` exists: create `.agents/agents` as a symlink → `../agents` + (skip if the symlink already exists) + - If `skills/` exists: create `.agents/skills` as a symlink → `../skills` + (skip if the symlink already exists) + +> **Note:** When Phase 2 §2.12 adds repo-local agents, the Agent Registration Rule +> (step 15) also creates or repairs `.codex/agents` and `.agents/agents`. There is no +> conflict — §1.13 creates the directories and initial symlinks in Phase 1; step 15 +> repairs them in Phase 2 after agents have been committed. + +**Files:** `.codex/` (with `agents` and/or `skills` symlinks when applicable); +`.agents/` (with `agents` and/or `skills` symlinks when applicable). + +**Done when:** `ls -la .codex/ .agents/` shows the directories and any symlinks point +to the correct relative targets (`../agents`, `../skills`). + +## Phase 1 Exit Gate + +Do not offer or start Phase 2 until every applicable Phase 1 item is in one of these states: +- completed and written +- explicitly skipped with a recorded reason +- not applicable because of repo type or tool selection +- already adequate and recorded as such +- explicitly declined by the user + +Phase 1 is **not** complete if any of the following is still true: +- a Phase 1 file draft is still awaiting approval +- an in-scope Phase 1 file has no final status +- the skipped-files report has not been shown +- there is unresolved uncertainty about whether a Phase 1 file should exist + +If any Phase 1 work is still pending, finish Phase 1 first and do not move to Phase 2. +After the Phase 1 Exit Gate passes, hand control back to `SKILL.md` / `PLAN.md`, stop using this +file as the active phase document, and only then load `phase-2.md`. + +## Phase 1 Completion: Skipped-Files Report + +After completing all applicable Phase 1 steps, output a table of every conditional file that was +not created, with the exact reason. Never silently skip a file. + +| File | Condition to create | Reason skipped | +|------|--------------------|----------------| +| `CLAUDE.md` | Claude Code selected | _(fill in)_ | +| `.claude/rules/*.md` | Claude Code selected; create only the convention files applicable to this repo | _(fill in)_ | +| `.github/copilot-instructions.md` | GitHub Copilot (IDE) selected | _(fill in)_ | +| `.cursorrules` | Cursor selected | _(fill in)_ | +| `.cursor/rules/*.mdc` | Cursor selected; create only the convention files applicable to this repo | _(fill in)_ | +| additional `.cursor/rules/*.mdc` | Cursor-only scoped rules are needed beyond `.cursorrules` and the shared Cursor rule files | _(fill in)_ | +| `.env.example` | Has-env-vars repos only | _(fill in)_ | +| `.github/workflows/ci.yml` | GitHub repos — explicit user confirmation required | _(fill in)_ | +| `.codex/` + `.agents/` | Codex / Gemini / Windsurf or generic AI tool selected | _(fill in)_ | + +This report must be shown even when the reason is obvious. It gives the user a clear picture of +what was done and what was intentionally deferred. diff --git a/plugins/aem/agentify/skills/agentify/references/phase-2.md b/plugins/aem/agentify/skills/agentify/references/phase-2.md new file mode 100644 index 00000000..82eaa3d2 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/phase-2.md @@ -0,0 +1,512 @@ +# Agentify Phase 2 + +Use this file for the full Phase 2 workflow. `PLAN.md` remains the top-level execution index, +but the canonical Phase 2 instructions live here. This document is self-sufficient for Phase 2: +once it becomes active, it replaces `phase-1.md` as the current phase instruction source. + +## Prerequisite Gate + +Phase 2 may start only after Phase 1 is fully complete. + +Before offering or starting any Phase 2 work, confirm all of the following: +- every applicable Phase 1 item is in a final state: completed and written, explicitly skipped + with a recorded reason, not applicable, already adequate, or explicitly declined by the user +- there is no pending Phase 1 draft awaiting approval +- every in-scope Phase 1 file has a final status +- the skipped-files report was shown + +If any Phase 1 work is still pending, stop and return to Phase 1. Do not begin Phase 2. + +Once the gate passes, assume all Phase 1 files exist in final approved form. If a mandatory Phase 1 +file is missing, return to Phase 1 rather than papering over the gap. + +## Skill Registration Rule + +See [skills-templates.md → Skill Registration Rule](skills-templates.md) for the full required +order. Apply it whenever any skill is created inside a target repo. + +## Prompt Registration Rule + +See [prompt-templates.md → Prompt Registration Rule](prompt-templates.md) for the full required +order. Apply it whenever the prompt library is created or updated inside a target repo. + +## Agent Registration Rule + +See [repo-agent-templates.md → Agent Registration Rule](repo-agent-templates.md) for the full +required order. Apply it whenever any repo-local helper agent is created inside a target repo. + +## Workflow Registration Rule + +**Applies whenever GitHub workflow automation is created, updated, or documented inside a target +repo.** + +After writing or reviewing the canonical workflow files under `.github/workflows/` and any related +shared helper scripts under `.github/scripts/`, always register the workflow surface in the exact +order below. This registration pass must cover the full current workflow surface in scope for the +repo section you are updating, not just the workflows changed in the current run. + +**Required order:** +1. Update the canonical workflow files under `.github/workflows/` and any touched shared helpers + under `.github/scripts/` when the current change modifies them. If the current change is only + documenting an already-existing workflow surface, read those files first and treat them as the + source material for the docs below. +2. Create or update `docs/workflows.md` so it covers the full current workflow surface in scope, + including both pre-existing workflows and workflows created or updated in the current run. +3. Create or update `.github/workflows/README.md` so it explains the detailed behavior for the + workflows currently in scope without duplicating the stable contract from `docs/workflows.md`. +4. Update `AGENTS.md` so the repository structure tree, `## Key Documentation`, and workflow + summary reflect the current workflow surface in scope. +5. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly approved + in Phase 2, update them so they reflect the current workflow surface and canonical workflow-doc + locations. Otherwise leave them untouched. +6. Refresh any affected projection or quick-reference files so they point back to `AGENTS.md`, + `docs/workflows.md`, or `.github/workflows/README.md` instead of duplicating workflow rules. + +## Decision Registration Rule + +**Applies whenever `docs/decisions/` is created or updated inside a target repo.** + +After writing the canonical ADR files under `docs/decisions/`, always register the decision set in +the exact order below. This registration pass must cover the full current ADR set in scope for the +repo section you are updating, not just the ADRs created in the current change. + +**Required order:** +1. Update the canonical ADR files under `docs/decisions/`. +2. Update `AGENTS.md` so the repository structure tree and `## Key Documentation` entry reflect + `docs/decisions/` as the canonical ADR location. +3. Update `README.md` only if it already mentions the generated Phase 2 decision-doc set and needs + a brief human-facing pointer refresh. Do not turn `README.md` into the ADR catalog. +4. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly approved + in Phase 2, update them so they reflect the ADR set and where it lives. Otherwise leave them + untouched. +5. Refresh any affected projection or quick-reference files so they continue to point back to + `AGENTS.md` rather than duplicating ADR content. + +## Surface API Registration Rule + +**Applies whenever helper-surface contract docs are created or updated inside `docs/`.** + +This rule covers focused contract docs for repo helper surfaces such as: +- `docs/workflows.md` +- `docs/skills.md` +- `docs/rules.md` +- `docs/prompts.md` +- `docs/agents.md` +- the top-level index `docs/api.md` + +These files are canonical only under `docs/`. Do not create helper-surface contract files such as +`skills/api.md`, `prompts/api.md`, `agents/api.md`, `.github/workflows/api.md`, or similar +surface-local duplicates. + +Each helper-surface contract doc must cover the full current surface in scope for that repo area, +including both items that already existed before the run and items created or updated in the +current run. Do not write these docs as change summaries or delta-only notes. + +After writing the canonical surface API docs, always register them in the exact order below. + +**Required order:** +1. Update the canonical surface API docs under `docs/`. +2. Update `AGENTS.md` so the repository structure tree and `## Key Documentation` entries reflect + the current surface API docs that exist in the repo. +3. Update `README.md` only when it already mentions the relevant helper surface and needs a brief + human-facing pointer refresh. Do not turn `README.md` into a detailed contract catalog. +4. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly approved + in Phase 2, update them so they reflect the current surface API docs and canonical locations. + Otherwise leave them untouched. +5. Refresh any affected projection or quick-reference files so they continue to point back to the + canonical contract docs instead of duplicating the contracts inline. + +## Phase 2 Registration Rule + +**Applies after any Phase 2 deliverable is written** (`wiki/architecture.md`, `wiki/code-flows.md`, +`wiki/code-flow-*.md`, `docs/runbooks.md`, `docs/decisions/`, `docs/testing.md`, +`docs/release-process.md`, `prompts/README.md`, root-level repo-aware helper agents under +`agents/`, etc.). + +After writing each Phase 2 file or prompt-library entry point, update `AGENTS.md` and any +affected projection quick-reference files. + +1. **Repository Structure tree** — add the new file or directory with a one-line description. +2. **Key Documentation section** — add or update the `## Key Documentation` table entry. +3. **Prompt Library section** — when `prompts/` changes, update `AGENTS.md#prompt-library` with + the **minimal** entry per prompt (path + one-liner). Update `prompts/README.md` with exhaustive + per-prompt documentation. Do not put exhaustive docs in `AGENTS.md`. +4. **Projection quick references** — when `prompts/` changes, refresh short pointers in selected + tool-local projection files so they point to `AGENTS.md#prompt-library` and `prompts/README.md`. +5. **Available Agents section** — when repo-local agents change, update `AGENTS.md#available-agents` + with the **minimal** entry per agent (name, path, one-line guardrails). Update `agents/README.md` + with exhaustive per-agent documentation. Do not put exhaustive docs in `AGENTS.md`. +6. **Projection quick references for agents** — when repo-local agents change, refresh the short + agent-catalog pointers in selected projection files (`CLAUDE.md`, `.cursorrules`, + `.github/copilot-instructions.md`) so they point to `AGENTS.md#available-agents` + and `agents/README.md`. +7. **Available Skills section** — when repo-local skills change, update `AGENTS.md#available-skills` + with the **minimal** entry per skill (name, path, one-line when-to-use). Update `skills/README.md` + with exhaustive per-skill documentation. Do not put exhaustive docs in `AGENTS.md`. +8. **Projection quick references for skills** — when repo-local skills change, refresh the short + skill-catalog pointers in selected projection files (`CLAUDE.md`, `.cursorrules`, + `.github/copilot-instructions.md`) so they point to `AGENTS.md#available-skills` + and `skills/README.md`. + +Do not duplicate long content in `AGENTS.md` table entries or projection files. `AGENTS.md` carries +the minimal index; exhaustive catalogs live in `prompts/README.md`, `agents/README.md`, and +`skills/README.md`. Show the `AGENTS.md` additions before writing. + +## Phase 2: Contract Clarity + +**Goal:** Make the codebase self-documenting so AI tools can reason about intent, not just syntax. + +### Presenting Phase 2 to the User + +Only after the prerequisite gate above passes: +- offer Phase 2 explicitly +- do not start Phase 2 work without asking +- do not assume defer +- keep this file as the only active phase document until Phase 2 is complete + +**Always applicable (offer first):** +- `2.1` `wiki/architecture.md` + `wiki/code-flows.md` + 3–4 `wiki/code-flow-*.md` pages +- `2.2` `docs/runbooks.md` +- `2.3` `docs/decisions/` +- `2.12` helper-surface docs: `prompts/README.md` + repo-aware prompts + root-level helper agents + focused API docs for workflows, skills, rules, prompts, and agents when those surfaces exist +- `2.5` `CHANGELOG.md` for versioned repos +- `2.6` `docs/release-process.md` for versioned repos + +**Conditionally applicable:** +- `2.4` `docs/testing.md` → Has-tests only +- `2.7` `docs/api.md` / `openapi.yaml` → Service only +- `2.8` public API overview + source-level API docs → Source repos with a public API surface +- `2.13` `evals/` → LLM-app only + +**When drafting any Phase 2 deliverable:** +1. Read relevant source files first. +2. Draft from actual repo content. +3. Show the draft and wait for approval. +4. Write only after approval. + +> `2.6` and `2.9` follow the boy-scout rule when touched. `2.1`–`2.5`, `2.7`, `2.12`, and the +> public API overview portion of `2.8` are one-time documentation or helper-surface tasks. + +### 2.1 — `wiki/architecture.md` (+ code-flow wiki pages) + +**When to apply:** All repo types. + +**What to do:** Write a one-to-two page architecture document covering system shape, major +components, data flow, external dependencies, and deployment model. Also create: +- `wiki/code-flows.md` — index page for generated workflow docs +- `wiki/code-flow-.md` — 3–4 low-level workflow pages + +Keep `wiki/architecture.md` high-level. Put path-by-path execution in the per-workflow pages. +Use Mermaid diagrams when possible. + +For multi-module repos, add a module topology section covering: +- root/aggregator module +- public API vs implementation vs tests/integrations/packaging modules +- which modules are safe to change in isolation +- which modules must stay version-aligned + +Each code-flow page should include: +- a short workflow title +- why the workflow matters +- entry points/components/files involved +- one Mermaid diagram + +Treat these pages as living docs: +- add a new page when the repo gains a new major workflow +- update matching pages when an existing workflow changes +- update index plus pages when workflows are renamed, split, or removed + +**Files:** Ensure `wiki/` exists; add `wiki/architecture.md`, `wiki/code-flows.md`, and 3–4 +`wiki/code-flow-.md` files. + +**GitHub wiki sync (GitHub repos only):** +1. Check whether the GitHub wiki is enabled: + ```bash + gh api repos/OWNER/REPO --jq '.has_wiki' + ``` +2. If false, enable it: + ```bash + gh api repos/OWNER/REPO -X PATCH -f 'has_wiki=true' + ``` +3. Try cloning the wiki repo: + ```bash + git clone git@github.com:OWNER/REPO.wiki.git /tmp/repo-wiki 2>&1 + ``` +4. If clone fails because the wiki is uninitialized, ask the user to create the first page in the + GitHub UI, then wait. +5. Copy updated wiki files into the wiki repo, commit, and push. + +**Done when:** An LLM reading only these wiki files can understand the repo shape and its key +workflows without guessing. + +### 2.2 — `docs/runbooks.md` + +**When to apply:** Repos with release, deploy, or important operational procedures. + +**What to do:** Document how to release, debug common failures, deploy, rotate secrets, handle +database migrations, and basic incident response. + +**Files:** New `docs/runbooks.md`. + +**Done when:** An on-call engineer or AI agent can perform the three most common operational tasks +without asking anyone. + +### 2.3 — `docs/decisions/` + +**When to apply:** All repo types. + +**What to do:** Create `docs/decisions/` and write lightweight ADRs for the 4-5 most important +past decisions that are currently tribal knowledge. Treat that as the default starting set, not a +hard cap: if the repo clearly has more than five independent, high-value decisions that agents or +contributors repeatedly need to understand, create more. + +Find likely candidates first: + +```bash +git --no-pager log --oneline --all -n 200 +``` + +If a commit message includes a JIRA key matching `[A-Z]+-[0-9]+`, use it directly. Never invent a +ticket ID. + +ADR format: + +```markdown +# ADR-0001: Title + +**Status:** Accepted +**Linked ticket:** PROJECT-123 +**Context:** Why was this decision needed? +**Decision:** What was decided? +**Consequences:** What are the trade-offs? +``` + +**Files:** New `docs/decisions/0001-*.md`, etc. + +After writing the ADR files, apply the **Decision Registration Rule** above. + +**Done when:** The default 4-5 highest-value "why did we do it this way?" questions are answered by +ADRs, and any additional repo-specific decisions worth preserving have also been captured. + +### 2.4 — `docs/testing.md` + +**When to apply:** Has-tests repos only. + +**What to do:** Document the test pyramid, fixture/mocks locations, targeted test commands, and +coverage thresholds. For multi-module repos, include module-aware test commands. + +**Files:** New `docs/testing.md`. + +**Done when:** An AI agent can place and write a correctly structured test by following this file +alone. + +### 2.5 — `CHANGELOG.md` + +**When to apply:** Repos with versioned releases. + +**What to do:** Create `CHANGELOG.md` using Keep a Changelog format, seeded from git history. + +**Files:** New `CHANGELOG.md`. + +**Done when:** Every released version has an entry and the last release can be answered from this +file alone. + +### 2.6 — `docs/release-process.md` + +**When to apply:** Repos that produce versioned releases or deployable artifacts. + +**What to do:** Use the Phase 0 assessment output rather than re-reading files unnecessarily. +Document: +- versioning strategy +- release ownership (manual vs CI-managed) +- pre-release checklist +- release flow +- post-release verification +- rollback + +For any repo that does versioned releases, **both `docs/release-process.md` and a `/release` +execution skill are required, non-deferrable deliverables**. +Create the `/release` skill as a separate deliverable immediately after +`docs/release-process.md` is written and confirmed. Do not skip, defer, or treat the skill as +optional — it is mandatory for versioned repos whenever release documentation is in scope. + +**Required execution order for the `/release` skill:** + +Follow the **Skill Registration Rule** in [skills-templates.md](skills-templates.md), applied to +`skills/release/`. If the target repo uses Codex, also create `skills/release/agents/openai.yaml` +with lightweight interface metadata after completing the registration steps. + +**Done when:** Any team member or AI agent can execute a release from scratch by following the +document alone. + +### 2.7 — Service API documentation + +**When to apply:** Service repos only. + +**What to do:** Document service boundaries using `docs/api.md`, `openapi.yaml`, `schemas/`, or +equivalent machine-readable contracts. + +**Done when:** An LLM can generate a valid API client from the documented contract alone. + +### 2.8 — Public API documentation + +**When to apply:** Source repos only. Boy-scout rule. + +**What to do:** Add in-file public API docs when touching files. Also, if the repo exposes a +public API surface, explicitly offer a repo-level public API overview. + +Use these targets: +- library/component repos: `docs/api.md` +- large code-heavy repos: `docs/api-overview.md` +- service repos: use `2.7` instead + +**Done when:** An LLM reading only the chosen overview file can answer what the public contract is +and which types are safe to call. + +### 2.9 — Configuration file comments + +**When to apply:** All repo types. Boy-scout rule. + +**What to do:** Add inline comments to non-obvious configuration entries. Explain why, not what. + +### 2.10 — Type annotations + +**When to apply:** Source repos using dynamic languages only. Boy-scout rule. + +**What to do:** Add type hints or type-like annotations to public function signatures when files +are touched. + +### 2.11 — Descriptive test names + +**When to apply:** Has-tests repos only. Boy-scout rule. + +**What to do:** Ensure test names encode what is tested, under what condition, and the expected +outcome. + +### 2.12 — `prompts/` + repo-aware helper agents + helper-surface API docs + +**When to apply:** All repo types. Highest priority for Multi-agent and LLM-app repos. + +**Before drafting:** +- read [prompt-templates.md](prompt-templates.md) when `prompts/` is in scope +- read [repo-agent-templates.md](repo-agent-templates.md) when helper agents are in scope +- read [skills-templates.md](skills-templates.md) when repo-local skills (other than `/release`) are in scope +- use recurring workflows discovered in Phase 0/1 and, when present, `wiki/code-flows.md` plus + matching `wiki/code-flow-*.md` pages as the source of truth + +**Helper-surface API docs to create when the matching surface exists or is generated in scope:** +- `docs/workflows.md` for workflow contracts +- `docs/skills.md` for repo-local skill contracts +- `docs/rules.md` for tool-local rules and projection-rule contracts +- `docs/prompts.md` for prompt-library contracts +- `docs/agents.md` for repo-local helper-agent contracts +- `docs/api.md` as the top-level index for those surface docs + +Do not create surface API docs for surfaces that do not exist in the target repo. Keep each doc +focused on one surface instead of combining all helper-surface contracts into one large file. +Create them only under `docs/`, never as `api.md` files colocated with the surface they describe. +Each doc should describe the whole current surface in scope, including both pre-existing and newly +created items, so a fresh reader can understand the repo without cross-referencing the diff. + +**Required execution order inside `2.12`:** +1. Create or update the canonical prompts under `prompts/`. +2. Create or update `prompts/README.md` with **exhaustive** per-prompt documentation — one + section per prompt covering: purpose, when to use, what it covers, how to invoke, expected + output, and repo-specific docs it references. This is the exhaustive prompt catalog; cover all + prompts in the repo, not just the ones created in this run. +3. Create or update `docs/prompts.md` so it covers the full current prompt surface in scope. +4. Update `AGENTS.md` `## Prompt Library` with the **minimal** entry per prompt (name, path, + and a brief when-to-use signal). Exhaustive docs go only in `prompts/README.md`. +5. Update `README.md` with only the brief human-facing prompt pointer. +6. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly + approved in Phase 2, update them so they reflect the prompt library and canonical `prompts/` + location. Otherwise leave them untouched. +7. Update projection files so they point to `AGENTS.md#prompt-library` and `prompts/README.md`. +8. Create or update the canonical helper agents under `agents/`. +9. Create or update `agents/README.md` with **exhaustive** per-agent documentation — one section + per agent covering: purpose, files, phases/workflow steps, invocation examples, expectations, + and constraints. This is the exhaustive agent catalog; cover all agents in the repo, not just + the ones created in this run. +10. Create or update `docs/agents.md` so it covers the full current agent surface in scope. +11. Update `AGENTS.md` `## Available Agents` with the **minimal** entry per agent (name, path, + brief when-to-use signal, and one-line guardrails). Exhaustive docs go only in `agents/README.md`. +12. Update `README.md` with only the brief human-facing agent pointer. +13. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly + approved in Phase 2, update them so they reflect the helper-agent catalog and canonical + `agents/` location. Otherwise leave them untouched. +14. Update projection files so they point to `AGENTS.md#available-agents` and `agents/README.md`. +15. Create or repair `.claude/agents`, `.codex/agents`, `.agents/agents`, `.cursor/agents`, and + `.github/agents`. +16. If the target repo has skills under `skills/`, create or update `skills/README.md` with + **exhaustive** per-skill documentation — one section per skill covering: purpose, trigger + phrases, argument usage, workflow steps, supporting files, and constraints. This is the + exhaustive skill catalog. Update `AGENTS.md` `## Available Skills` with the **minimal** entry + only. +17. Create or update the remaining helper-surface API docs under `docs/` for every other in-scope + surface that now exists and was not already covered above, typically workflows and rules. In + each doc, cover the full current surface in scope, including both pre-existing and newly + created items. +18. Update `docs/api.md` so it serves as the index for the focused helper-surface API docs rather + than the only place those contracts are described. +19. Apply the **Surface API Registration Rule** above. + +Typical prompt baseline: + +```text +prompts/ + README.md + repo/ + explain-the-repo.md + plan-a-change.md + review-a-change.md +``` + +Typical helper-agent baseline: + +```text +agents/ + explain-the-repo/ + AGENT.md + openai.yaml + plan-a-change/ + AGENT.md + openai.yaml + review-a-change/ + AGENT.md + openai.yaml +``` + +Create 3–5 prompts and 3–5 helper agents by default. This is guidance, not a hard cap. + +For LLM-app repos, keep helper prompts under `prompts/repo/` and store runtime prompts under +`prompts/system/`, `prompts/tasks/`, and `prompts/templates/` as applicable. + +Every helper agent must: +- automate a real, repeated repo code flow +- reference actual repo docs, commands, paths, and output expectations +- point back to `AGENTS.md` and deeper workflow docs rather than duplicating them +- stay focused on one workflow +- use lightweight `openai.yaml` only when Codex is selected +- live canonically under `agents/` + +**Done when:** A newcomer can use `prompts/README.md` and the generated helper agents to work in +the repo without reverse-engineering the layout first. + +### 2.13 — `evals/` + +**When to apply:** LLM-app repos only. + +**What to do:** Create `evals/` containing evaluation cases, golden outputs, and scripts that run +evals and report pass/fail. Add eval runs to CI when prompt/model files change. + +### 2.14 — `schemas/` + +**When to apply:** Service or LLM-app repos with important data contracts. + +**What to do:** Create machine-readable schemas for data crossing system boundaries. + +### 2.15 — `fixtures/` or `scripts/seed.*` + +**When to apply:** Has-tests repos where reproducible test data matters. + +**What to do:** Add seed data, factories, and mock responses needed to run tests consistently. diff --git a/plugins/aem/agentify/skills/agentify/references/phase-3.md b/plugins/aem/agentify/skills/agentify/references/phase-3.md new file mode 100644 index 00000000..7491a641 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/phase-3.md @@ -0,0 +1,123 @@ +# Agentify Phase 3 + +Use this file for the full Phase 3 workflow. `PLAN.md` remains the top-level execution index, +but the canonical Phase 3 instructions live here. This document is self-sufficient for Phase 3: +while it is active, do not load or use `phase-4.md` as an execution source. + +## Scope And Prerequisites + +- Start only after Phase 2 is complete. +- Use this file for all `3.1`–`3.6` work and for Phase 3 triage. +- Keep this file as the active Phase 3 instruction source when Phase 3 items are being assessed or executed. +- For applicability, effort, and priority lookup, use [plan-reference.md](plan-reference.md). +- Phase 3 does not depend on Phase 4 content. Triaging or deferring Phase 4 does not affect how + Phase 3 itself is evaluated. + +## Phase 3: Structural Improvements + +**Goal:** Reduce implicit context and make the codebase navigable by AI tools. + +> All steps follow the **boy-scout rule** unless otherwise noted. + +## Default Triage For Phase 3 + +Do not treat all of Phase 3 as automatic defer work, but structural changes should still be +handled conservatively. + +- **Do now** when a Phase 3 step is low-risk, tightly scoped, and naturally overlaps with files + already being changed in the current session. +- **Offer now** when a structural improvement is clearly valuable but requires an explicit user + decision about scope, rollout cost, or architectural tradeoffs. +- **Defer** when the work is a broader refactor that is better handled during a future change + touching the same code paths. + +**Default guidance:** +- **Do now:** only narrowly scoped structural cleanup that cleanly fits the current change +- **Offer now:** bounded structural improvements the user may want to include in the current round +- **Defer:** most of Phase 3 (`3.1`–`3.6`) unless the current session is already modifying those + code paths or the user explicitly wants the structural follow-up now + +When presenting Phase 3, say which applicable steps fall into which bucket and why. + +After classification: +- execute `Do now` items in the current session +- present `Offer now` items to the user before doing them +- record `Defer` items so they appear in the completion report as explicit follow-up work + +### 3.1 — Centralised Configuration (`src/config/` or module-level equivalent) + +**When to apply:** **Source** repos that have model choices, feature flags, or runtime configuration scattered across multiple files. + +**What to do:** Create a `src/config/` directory (or equivalent per language convention) that centralises all runtime configuration: model selection, feature flags, timeouts, retry counts, external service URLs. + +No configuration value should be defined in more than one place. Application code reads from this single location. + +In **Multi-module** repos, interpret this at the module boundary: shared configuration belongs in a shared module or parent configuration layer; module-specific runtime config stays with that module. + +**Files:** New `src/config/` (or `config/`) directory with dedicated config files per concern. + +**Done when:** Changing a model name, feature flag, or timeout requires editing exactly one file. Grep for config values produces one result. + +**Skip if:** The repo is packaging-only, infrastructure-only, or documentation-only with no runtime config. + +### 3.2 — Centralised Logging (`src/lib/logger.*` or shared module equivalent) + +**When to apply:** **Source** repos only. + +**What to do:** Create a single logging module (`src/lib/logger.*` or language equivalent). All logging in the application goes through this module. Document: log levels used, structured fields required, correlation ID conventions, where logs are shipped. + +In **Multi-module** repos, this may be a shared library module rather than a single `src/lib/` path at the repo root. + +**Files:** New `src/lib/logger.*` (or equivalent). + +**Done when:** `grep -r "console.log\\|System.out.print\\|print(" src/` (or language equivalent) returns zero hits. All log statements use the centralised logger. + +**Skip if:** The repo is packaging-only, infrastructure-only, or uses a framework that provides logging (e.g., OSGi SLF4J already centralises logging in AEM projects). + +### 3.3 — Eliminate Magic Values + +**When to apply:** **Source** and **Infra** repos. Boy-scout rule. + +**What to do:** Replace magic numbers, hardcoded strings, and unexplained literals with named constants. + +Bad: `if (retryCount > 3)` — Good: `if (retryCount > MAX_RETRY_ATTEMPTS)` + +**Done when:** Grep for numeric literals (excluding 0 and 1) and string literals in conditional expressions returns fewer than 5 unexplained hits per 1000 lines of code. + +### 3.4 — Reduce Method Length and Complexity + +**When to apply:** **Source** repos. Boy-scout rule — apply only to methods being modified. + +**What to do:** When modifying a method longer than 30 lines or with cyclomatic complexity above 10, extract well-named helper methods. + +**Done when:** No newly written or modified method exceeds 40 lines or cyclomatic complexity of 10. Measure with Checkstyle, ESLint, Pylint, or SonarQube. + +### 3.5 — Make Dependencies Explicit + +**When to apply:** **Source** repos. Boy-scout rule. + +**What to do:** Replace service locator patterns with constructor injection. Replace global state accessed via static methods with injected dependencies. Replace implicit ordering with explicit state machines or builder patterns. + +**Done when:** For any class, an LLM can determine all its dependencies by reading the constructor (or import list for functional code) alone. + +### 3.6 — Organise Directory Structure To Reflect Architecture + +**When to apply:** **Source** and **Infra** repos with flat or confusing directory layouts. NOT a boy-scout item — plan deliberately. + +**What to do:** Organise sub-packages/modules to reflect architectural boundaries. Do this module-by-module during natural refactoring milestones, not as a big-bang rename. + +**Done when:** The output of `tree` tells the architectural story. Major components and their relationships are inferable from directory names alone. + +**Repo type notes:** +- **Multi-module:** Prefer clear parent/child module boundaries over forcing every module to be top-level. Group modules by role (`core`, `store`, `segment`, `search`, `benchmarks`, `it`, `examples`, etc.) and document the reason each grouping exists. +- **Monorepo:** Each independently deployable unit should be a top-level directory with its own README, build file, and `CLAUDE.md`. +- **Packaging-only:** This step rarely applies. + +## Phase 3 Completion + +When the selected Phase 3 work is complete: +- summarize what was done now, what was offered, and what was deferred +- confirm there is no pending Phase 3 draft or unresolved Phase 3 decision still blocking handoff +- hand control back to `SKILL.md` / `PLAN.md` +- stop using this file as the active phase document +- continue with Phase 4 by loading `phase-4.md` diff --git a/plugins/aem/agentify/skills/agentify/references/phase-4.md b/plugins/aem/agentify/skills/agentify/references/phase-4.md new file mode 100644 index 00000000..7b822c8e --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/phase-4.md @@ -0,0 +1,185 @@ +# Agentify Phase 4 + +Use this file for the full Phase 4 workflow. `PLAN.md` remains the top-level execution index, +but the canonical Phase 4 instructions live here. This document is self-sufficient for Phase 4: +once it becomes active, it replaces `phase-3.md` as the current phase instruction source. + +## Scope And Prerequisites + +- Start only after Phase 3 triage is complete and any selected Phase 3 work has reached final + state. +- Use this file for all `4.1`–`4.8` work and for Phase 4 triage. +- Keep this file as the active Phase 4 instruction source when Phase 4 items are being assessed or executed. +- For applicability, effort, and priority lookup, use [plan-reference.md](plan-reference.md). +- Phase 4 does not depend on Phase 3 content. It may begin after the Phase 3 handoff even when + some Phase 3 items were explicitly deferred. + +## Phase 4: Automation And Ongoing Hygiene + +**Goal:** Prevent regression and ensure AI-nativeness improves over time. + +## Default Triage For Phase 4 + +Phase 4 contains a mix of immediate quick wins and larger follow-up work. Do not present it as +universally deferred. + +- **Do now** when the work is a lightweight additive change that improves future agent work + immediately without redesigning the repo's tooling. +- **Offer now** when the work is valuable but needs an explicit user decision on rollout cost, + CI/tooling changes, or operational scope. +- **Defer** only when the work is a broader process change that is better handled in a dedicated + follow-up effort. + +**Default guidance:** +- **Do now:** `4.3` PR template, `4.8` living-document rule, and `4.1` / `4.4` when they are + lightweight additive changes that fit the current repo tooling without redesigning CI +- **Offer now:** `4.1` when CI needs a broader redesign, `4.2` pre-commit hooks, `4.5` + observability baseline, `4.6` security and ops docs, `4.7` periodic audit process +- **Defer:** only the larger rollout items that do not fit the current session cleanly + +When presenting Phase 4, say which applicable steps fall into which bucket and why. + +After classification: +- execute `Do now` items in the current session +- present `Offer now` items to the user before doing them +- record `Defer` items so they appear in the completion report as explicit follow-up work + +### 4.1 — CI Pipeline (Formatting, Linting, Tests, Type Checks) + +**When to apply:** All repo types with a CI system. + +**What to do:** Ensure CI runs on every PR and covers all applicable checks: + +| Check | Tools | +|-------|-------| +| Formatting | Spotless, Prettier, Black, gofmt | +| Linting | Checkstyle, ESLint, Pylint, golint | +| Tests | JUnit, pytest, Jest, go test | +| Coverage report | JaCoCo, coverage.py, nyc, go cover | +| Type check | tsc, mypy, pyright | +| Eval runs | Custom eval script (LLM-app repos only) | + +Use `.github/workflows/ci.yml` for GitHub Actions, or extend Jenkinsfile/GitLab CI. + +**Files:** `.github/workflows/ci.yml` or equivalent CI config. + +**Done when:** Every PR is blocked if formatting, linting, or tests fail. Coverage report is published as a PR comment. + +### 4.2 — Pre-Commit Hooks + +**When to apply:** **Source** and **Infra** repos. + +**What to do:** Configure pre-commit hooks that enforce formatting and linting before every commit. Use the pre-commit framework () for multi-language repos. + +- Java: Spotless, Checkstyle +- Python: Black, Ruff, isort +- JavaScript/TypeScript: Prettier, ESLint +- Go: gofmt, golint + +**Files:** `.pre-commit-config.yaml` or equivalent. + +**Done when:** Malformatted code cannot be committed. Running the formatter on any file after a commit produces no changes. + +### 4.3 — `.github/PULL_REQUEST_TEMPLATE.md` + +**When to apply:** All repo types hosted on GitHub. + +**What to do:** Create `.github/PULL_REQUEST_TEMPLATE.md`: + +```markdown +## Summary +[What changed and why] + +## Changes +[Key files/methods changed] + +## Test Plan +- [ ] New tests added +- [ ] Existing tests pass +- [ ] Manual testing performed (describe) + +## AI Review Notes +[Any context that helps Copilot or other AI reviewers understand the change] +``` + +**Files:** New `.github/PULL_REQUEST_TEMPLATE.md`. + +**Done when:** Every PR follows the template. "AI Review Notes" is populated for non-obvious changes. + +### 4.4 — CI Documentation Coverage Check + +**When to apply:** **Source** repos with public APIs. + +**What to do:** Add a CI step that warns (not blocks initially) when public methods lack documentation. + +- Java: Checkstyle `MissingJavadocMethod` +- Python: `interrogate` or `pydocstyle` +- JavaScript/TypeScript: `eslint-plugin-jsdoc` + +**Done when:** CI reports documentation coverage percentage on every PR. The metric trends upward over time. + +### 4.5 — Observability Baseline + +**When to apply:** **Source** repos deployed to a runtime environment. + +**What to do:** Document and enforce observability basics in `AGENTS.md` and `CONTRIBUTING.md`. +If tool-local projection files are in scope for the selected tools, sync their short pointers after +updating `AGENTS.md`: + +- **Logging conventions**: log levels, structured fields, correlation IDs, what must always be logged (errors, slow operations, external calls) +- **Error handling**: how errors are caught, wrapped, and surfaced — never silently swallowed +- **Tracing**: if distributed tracing is used, document the span naming convention and where to find traces + +Ensure new code follows these conventions. Add a CI lint rule if feasible. + +**Done when:** Any developer (or AI agent) adding a new feature knows exactly what to log, how to handle errors, and how to instrument spans without asking. + +**Skip if:** The repo is packaging-only, infrastructure-only, or produces no running process. + +### 4.6 — Security And Ops Docs + +**When to apply:** All repo types that handle secrets, user data, or have deploy steps. + +**What to do:** Document in `docs/runbooks.md` or a dedicated `docs/security.md`: + +- Where secrets live and how they are injected (never hardcoded) +- Permission model: who/what has access to which resources +- Database migration process (if applicable) +- Deploy steps in order +- Rollback procedure + +**Done when:** A new team member can handle a credential rotation or a failed deployment without asking anyone. + +### 4.7 — Periodic AI-Nativeness Audits + +**When to apply:** All repo types. + +**What to do:** Quarterly, re-run Phase 0 and score the repo against all applicable steps in this plan. Track metrics: + +- Documentation coverage (% of public methods with docs) +- Test coverage (line and branch %) +- Magic value count per 1000 lines +- Average method length +- Number of files without any associated test +- Plan step completion count (applicable steps present vs total applicable) + +**Done when:** Metrics improve or hold steady quarter-over-quarter. Any regression has a documented root cause. + +### 4.8 — `AGENTS.md` As A Living Document + +**When to apply:** All repo types. + +**What to do:** Add to the team's definition-of-done: "If this change alters build steps, +conventions, architecture, deployment, prompts, or repo-local agents, update `AGENTS.md` first." +Treat `AGENTS.md` like a Dockerfile — it must always reflect reality. After updating it, sync the +tool-local projection files in the same change. + +**Done when:** `AGENTS.md` was last modified within the last 30 days (for active repos), and the +tool-local projections still accurately point back to it. + +## Phase 4 Completion + +When the selected Phase 4 work is complete: +- summarize what was done now, what was offered, and what was deferred +- hand control back to `SKILL.md` / `PLAN.md` +- continue to verification, completion reporting, or post-PR flow as appropriate diff --git a/plugins/aem/agentify/skills/agentify/references/plan-reference.md b/plugins/aem/agentify/skills/agentify/references/plan-reference.md new file mode 100644 index 00000000..cc0a1c65 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/plan-reference.md @@ -0,0 +1,75 @@ +# Agentify Plan Reference + +Lookup material that supports the main execution flow in `PLAN.md`. + +## Quick Reference: When to Apply Each Step + +| Step | Source | Packaging | Infra | Multi-module | Monorepo | Docs | LLM-app | Service | Has-tests | Has-env-vars | Multi-agent | +|------|:------:|:---------:|:-----:|:------------:|:--------:|:----:|:-------:|:-------:|:---------:|:------------:|:-----------:| +| 1.1 CLAUDE.md | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.2 README.md | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.3 CONTRIBUTING.md | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.4 CODEOWNERS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.5 copilot-instructions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.6 AGENTS.md (Codex/Copilot Workspace) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.7 .cursorrules + `.cursor/rules/*.mdc` | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | Cursor selected | +| 1.8 .editorconfig | ✅ | ✅ | ✅ | ✅ | ✅ | optional | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.9 .gitignore | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.10 .env.example | — | — | — | — | — | — | — | — | — | ✅ | — | +| 1.11 .claude/settings.json + `.claude/rules/*.md` (Claude Code only) | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | Claude Code | +| 1.12 .github/workflows/ci.yml | ✅ | optional | ✅ | ✅ | ✅ | optional | ✅ | ✅ | ✅ | ✅ | ✅ | +| 1.13 .codex/ + .agents/ (Codex/generic tools) | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | Codex/generic | +| 2.1 wiki/architecture.md (+ code-flow docs) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 2.2 docs/runbooks.md | ✅ | ✅ | ✅ | ✅ | ✅ | helpful | ✅ | ✅ | ✅ | ✅ | ✅ | +| 2.3 docs/decisions/ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 2.4 docs/testing.md | — | — | — | helpful | helpful | — | — | — | ✅ | — | — | +| 2.5 CHANGELOG.md | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 2.6 docs/release-process.md | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 2.7 docs/api.md / openapi | — | — | — | depends | depends | — | ✅ | ✅ | — | — | — | +| 2.8 Public API docs | ✅ | deps only | scripts | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 2.9 Config file comments | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | +| 2.10 Type annotations | dyn. langs | — | scripts | dyn. langs | dyn. langs | — | dyn. langs | dyn. langs | — | — | — | +| 2.11 Test naming | — | — | — | — | — | — | — | — | ✅ | — | — | +| 2.12 prompts/ + repo-aware helper agents | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 2.13 evals/ | — | — | — | — | — | — | ✅ | — | — | — | — | +| 2.14 schemas/ | — | — | — | depends | depends | — | ✅ | ✅ | — | — | — | +| 2.15 fixtures/ | — | — | — | helpful | helpful | — | — | — | ✅ | — | — | +| 3.1 src/config/ | ✅ | — | — | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 3.2 src/lib/logger.* | ✅ | — | — | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 3.3 Magic values | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 3.4 Method length | ✅ | — | scripts | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 3.5 Explicit deps | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 3.6 Directory structure | ✅ | rarely | ✅ | critical | critical | — | ✅ | ✅ | — | — | — | +| 4.1 CI pipeline | ✅ | optional | ✅ | ✅ | ✅ | optional | ✅ | ✅ | ✅ | — | — | +| 4.2 Pre-commit hooks | ✅ | optional | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 4.3 PR template | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 4.4 Doc coverage CI | ✅ | — | — | ✅ | ✅ | — | ✅ | ✅ | — | — | — | +| 4.5 Observability baseline | ✅ | — | — | depends | ✅ | — | ✅ | ✅ | — | — | — | +| 4.6 Security and ops docs | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | ✅ | — | +| 4.7 Periodic audits | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 4.8 Living AGENTS.md | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + +## Estimated Effort by Phase + +| Phase | Typical Effort | Expected Impact | +|-------|---------------|-----------------| +| Phase 0: Assessment | 2–4 hours | Foundation — prevents wasted effort | +| Phase 1: High-ROI wins | 1–2 hours per repo | High — AGENTS.md alone improves AI accuracy by 50%+ | +| Phase 2: Contract clarity | 1–2 days for new docs, prompt libraries, and helper agents, plus ongoing upkeep when explicitly selected or already present | Medium-High — cumulative as structural coverage grows | +| Phase 3: Structural | Ongoing (varies per change) | Medium — reduces hallucination on complex reasoning | +| Phase 4: Automation | 4–8 hours initial setup | High for sustainability — prevents regression | + +## Priority Order + +1. **`AGENTS.md`** — single highest-impact action; vendor-neutral SSoT read by all major AI tools +2. **`CLAUDE.md`** — Claude Code's pointer to `AGENTS.md`; create immediately after `AGENTS.md` +3. **`.cursorrules`** — when Cursor is selected, create its pointer to `AGENTS.md` +4. **`.github/CODEOWNERS`** — always create; controls PR review routing for humans and AI tools +5. **`README.md`** — fixes the universal entry point +6. **`CONTRIBUTING.md`** — defines the behavioural contract for humans and AI agents +7. **`.github/copilot-instructions.md`** — Copilot IDE's pointer to `AGENTS.md` +8. **`wiki/architecture.md`** + **`wiki/code-flows.md`** + **`wiki/code-flow-*.md`** + **`docs/runbooks.md`** + **`prompts/README.md`** + **repo-aware helper agents under `agents/`** + **`agents/README.md`** — operational and structural context; `skills/README.md` belongs here too for repos that have skills +9. **`docs/decisions/`** — captures tribal knowledge before it is lost +10. **Everything else** — boy-scout rule, incrementally, when files are touched + +> The boy-scout rule is the key sustainability mechanism: **never do a big-bang rewrite — improve incrementally every time a file is touched.** diff --git a/plugins/aem/agentify/skills/agentify/references/prompt-templates.md b/plugins/aem/agentify/skills/agentify/references/prompt-templates.md new file mode 100644 index 00000000..82078594 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/prompt-templates.md @@ -0,0 +1,194 @@ +# Agentify Prompt Templates + +Use this reference when `references/phase-2.md` §2.12 (`prompts/`) is in scope. + +## Goal + +Create a small `prompts/` library that helps humans and agents work effectively in the target +repo without guessing where to start. These prompts must be **repo-aware**: they should name the +real build/test commands, key docs, important directories, and repo-specific guardrails discovered +earlier in the agentify flow. + +## Rules + +- Do not duplicate `AGENTS.md` verbatim. Prompt files should point back to `AGENTS.md` and other + docs, then restate only the few repo facts needed for the task. +- Keep each prompt focused on one job. Avoid giant "do everything" prompts. +- Prefer concrete repo paths, module names, commands, and contracts over placeholders. +- Use Markdown so the prompts are easy to read and edit in git. +- Keep the library small. Start with 3-5 high-value prompts by default, then add optional prompts + only when the repo type clearly calls for them. This is guidance, not a hard limit — create + more when the repo has enough distinct, commonly used workflows to justify it. +- For simple repos, keep the library lean: create the baseline prompts, keep them concise, and + avoid repeating large chunks of `AGENTS.md`, `README.md`, or existing runbooks. +- If agentify also creates repo-aware helper agents for the same workflows, keep prompt names, + cited docs, and repo terminology aligned so the prompt and agent entry points reinforce the + same code flows. +- Prompts are the lightweight human-readable starting point. Repo-aware helper agents are the + executable workflow surface. Do not duplicate full workflow instructions in both. +## Baseline Prompt Set + +Create these files for most repos: + +- `prompts/README.md` +- `prompts/repo/explain-the-repo.md` +- `prompts/repo/plan-a-change.md` +- `prompts/repo/review-a-change.md` + +Add `prompts/repo/debug-a-failure.md` when the repo has runtime behavior, tests, infra, or a +service surface worth debugging. + +## Optional Prompt Set + +Create these only when the repo type or workflow makes them clearly useful: + +- `prompts/repo/add-or-fix-tests.md` for `Has-tests` repos +- `prompts/repo/prepare-a-release-change.md` for versioned repos or repos with a documented release process +- `prompts/repo/work-in-a-module.md` for `Multi-module` or `Monorepo` repos with non-obvious boundaries + +For `LLM-app` repos, keep helper prompts under `prompts/repo/` and store application prompts in +dedicated subdirectories such as `prompts/system/`, `prompts/tasks/`, and `prompts/templates/`. +Do not mix user helper prompts and runtime application prompts in the same folder. + +## Repo Facts to Inject + +Every generated prompt should include the subset of these facts that matters for its task: + +- Repo name and one-line purpose +- Primary languages/frameworks and build system +- Canonical docs to read first, usually `AGENTS.md`, `README.md`, and one or two deeper docs +- Build, test, lint, and typecheck commands when they exist +- Important directories, modules, or entry points +- Repo-specific "must not do" rules, immutable APIs, or release/versioning constraints +- Expected output format for the task (plan, patch, findings, root cause summary, etc.) + +## Recommended File Pattern + +Each prompt file should follow this rough shape: + +```markdown +# + +Use this when: + +Before you start: +- Read `AGENTS.md` +- Read <1-2 repo-specific docs or paths> +- Use `` to validate when relevant + +Repo context: +- Purpose: +- Stack: +- Important paths: ``, `` +- Constraints: + +Prompt: + +``` + +## Template Guidance + +### `prompts/README.md` + +Purpose: +- Serve as the **exhaustive prompt catalog** — one section per prompt with full documentation +- Explain what lives under `prompts/` and how it relates to `AGENTS.md` +- Tell users to treat the files as starting points, not rigid scripts +- Keep `AGENTS.md#prompt-library` as the minimal index (path + one-liner per prompt); do not duplicate the exhaustive docs there + +Required structure for each prompt section: +- Name and one-line purpose +- When to use (concrete trigger conditions) +- What it covers (bullet list of scope) +- How to invoke (exact invocation example) +- Expected output (what the prompt produces) +- Repo-specific docs it references + +This file covers all prompts in the repo, not just the ones created in the current run. + +### `prompts/repo/explain-the-repo.md` + +Prompt goal: +- Help a user or agent understand the repo quickly +- Ask for a concise architecture map, important modules, key commands, and risky areas + +Include: +- Which docs to read first +- Which directories/modules matter most +- A request to call out immutable contracts and common footguns + +### `prompts/repo/plan-a-change.md` + +Prompt goal: +- Produce a scoped implementation plan before editing + +Include: +- The commands to validate after the change +- A request to search for existing patterns before proposing new structure +- A requirement to list risks, affected files, and tests to update + +### `prompts/repo/review-a-change.md` + +Prompt goal: +- Run a review with findings-first output + +Include: +- A reminder to prioritize correctness, regressions, missing tests, and contract drift +- The repo's normal validation commands +- A request to use file/line references in findings + +### `prompts/repo/debug-a-failure.md` + +Prompt goal: +- Triage a broken build, failing test, incident, or runtime issue + +Include: +- Where logs, workflows, runbooks, fixtures, or sample inputs live +- Commands for reproducing locally +- A request to separate confirmed facts from hypotheses + +### Optional prompts + +`add-or-fix-tests.md` +- Ask for the narrowest tests that prove behavior and guard regressions +- Name the repo's test framework and command + +`prepare-a-release-change.md` +- Point to `docs/release-process.md` and versioning rules +- Ask for release-impact analysis and files that must stay in sync + +`work-in-a-module.md` +- Describe the module map and module boundaries +- Ask the agent to state cross-module impact before changing shared code + +## Prompt Registration Rule + +**Applies whenever the prompt library is created or updated inside a target repo.** + +After writing the canonical files under `prompts/`, always register the prompt library in the +exact order below. + +**Required order:** +1. Update the canonical prompt files under `prompts/`. +2. Create or update `prompts/README.md` with exhaustive per-prompt documentation. For each + prompt include: purpose, when to use it, what it covers, how to invoke it, expected output, + and any repo-specific docs or commands it references. `prompts/README.md` is the exhaustive + prompt catalog — one well-documented section per prompt, covering all prompts present in the + repo, not just the ones changed in this run. +3. Create or update `docs/prompts.md` so it covers the full current prompt surface in scope, + including both pre-existing prompts and prompts created or updated in the current run. +4. Update `AGENTS.md` with the **minimal** entry for the full current prompt set in the repo. + Document for each prompt or prompt group only: + - path under `prompts/` + - when to use it + - how to use it + - what output or task it is meant to drive + Do not copy the exhaustive documentation from `prompts/README.md` into `AGENTS.md`. + `AGENTS.md` is the minimal index; `prompts/README.md` is the exhaustive catalog. +5. Update `README.md` with a brief human-facing note and point back to `AGENTS.md`. +6. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly + approved in Phase 2, update them so they reflect the prompt library and canonical `prompts/` + location. Otherwise leave them untouched. +7. Refresh the projection files so they point back to `AGENTS.md#prompt-library`. + +`AGENTS.md` is the minimal index. `prompts/README.md` is the exhaustive catalog. diff --git a/plugins/aem/agentify/skills/agentify/references/release-skill-template.md b/plugins/aem/agentify/skills/agentify/references/release-skill-template.md new file mode 100644 index 00000000..15ffc3d6 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/release-skill-template.md @@ -0,0 +1,177 @@ +--- +name: release +description: > + Execute the release process for this repository by following docs/release-process.md. + Handles Maven (even/odd and semver), npm, and CI-managed (Jenkins / GitHub Actions) releases. + Confirms with the user at every irreversible step. Trigger phrases: "cut a release", + "release this repo", "run the release process", "do a release", "release version X". +tools: [Bash, Read, Edit, Glob, Grep] +--- + +# release Skill + +Executes this repository's release process step by step, following `docs/release-process.md` +as the single source of truth. Confirms before every irreversible operation. + +## Supporting Files + +| File | Purpose | Load when | +|------|---------|-----------| +| [references/maven-release.md](references/maven-release.md) | Maven release plugin commands, even/odd versioning, troubleshooting | When the repo uses Maven. Path resolves to `skills/release/references/maven-release.md` in the target repo. | + +--- + +## GLOBAL RULES + +1. **Never run `mvn release:prepare` or `mvn release:perform` without explicit user confirmation.** These operations push commits and tags to remote — they cannot be undone without manual cleanup. +2. **Always show the exact commands before running them.** State: what the command does, what it will change, whether it can be reversed. Wait for the user to say yes. +3. **Never skip pre-release checks.** Tests must pass and there must be no unintended SNAPSHOT dependencies before proceeding. +4. **If `docs/release-process.md` does not exist**, stop and tell the user. Do not attempt to infer the release process from `pom.xml` alone. +5. **If a step fails**, stop immediately. Do not attempt rollback without user approval. Show the error and ask how to proceed. +6. **If the release doc specifies CI-managed release, use it.** When `docs/release-process.md` says that a Jenkinsfile or GitHub Actions workflow owns the release, follow that CI workflow and do not run manual Maven commands in parallel. If the doc is ambiguous or silent about this, inspect the CI configuration and ask the user which path (CI-managed vs manual) is canonical before proceeding. + +--- + +## STEP 0 — Read the Release Process Doc + +1. Verify `docs/release-process.md` exists: + ```bash + cat docs/release-process.md + ``` + If it does not exist, stop and tell the user. + +2. Read the file and identify: + - Versioning strategy (even/odd, semver, or other) + - Release method (manual Maven, Jenkins, GitHub Actions, npm) + - Pre-release checklist items + - Post-release verification steps + +3. Determine the release version: + - If the user provided a version as an argument (`$ARGUMENTS`), use it + - Otherwise, read the current version from `pom.xml` / `package.json` and propose the next release version based on the versioning strategy + - For even/odd: current `1.3.0-SNAPSHOT` → propose release `1.4.0`, next dev `1.5.0` (Maven appends `-SNAPSHOT` via `-DdevelopmentVersion`) + - For semver: ask the user — PATCH, MINOR, or MAJOR bump? + +4. Show the user: + - Current version + - Proposed release version + - Proposed next development version + - Release method to be used + + Ask: "Is this correct? Confirm to proceed." + + Do not continue until the user confirms. + +--- + +## STEP 1 — Pre-Release Checks + +Run every item from the "Pre-Release Checklist" in `docs/release-process.md`. At minimum: + +```bash +# Verify tests pass +mvn verify -B # Maven +# or: npm test # Node.js + +# Check for unintended SNAPSHOT dependencies (Maven only) +# Compute current version once, then filter it out (see references/maven-release.md § Pre-Release Commands) +CURRENT=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout) +SNAPSHOTS=$(mvn dependency:list | grep -F SNAPSHOT | grep -vF "$CURRENT" || true) +if [ -n "$SNAPSHOTS" ]; then + echo "ERROR: Unintended SNAPSHOT dependencies found. Please remove them before releasing." + echo "$SNAPSHOTS" + exit 1 +fi + +# Verify working tree is clean +git status +``` + +Show the output. If any check fails, stop and report the failure — do not proceed. + +If all checks pass, tell the user and ask for confirmation to proceed. + +--- + +## STEP 2 — Execute the Release + +Choose the correct path based on what `docs/release-process.md` says: + +### Path A: CI-managed (Jenkins / GitHub Actions) + +Show the user the CI trigger command or UI steps from the release doc. Ask for confirmation. Do not run anything automatically — guide the user through the steps. + +Monitor the outcome. Move to STEP 3 once the CI release job completes successfully. + +### Path B: Manual Maven + +For detailed Maven commands, read **`$SKILL_DIR/references/maven-release.md`**. + +Show the user the exact commands that will run: + +```bash +mvn release:prepare -B \ + -DreleaseVersion= \ + -DdevelopmentVersion=-SNAPSHOT # is base version only, e.g. 1.5.0 + +mvn release:perform -B +``` + +Ask: "Ready to run these commands? This will commit, tag, and push to remote." + +Run only after explicit confirmation. + +### Path C: npm + +```bash +npm version +npm publish +git push --follow-tags +``` + +Show the commands first. Ask for confirmation before running. + +--- + +## STEP 3 — Post-Release Verification + +Run every item from the "Post-Release Verification" section in `docs/release-process.md`. At minimum: + +```bash +# Verify tag was pushed +# TAG_NAME is typically -; check in pom.xml +git ls-remote --tags origin | grep + +# Verify current version is now the next SNAPSHOT (Maven) +mvn help:evaluate -Dexpression=project.version -q -DforceStdout +``` + +If a verification step fails, report it and stop. Do not mark the release as complete. + +--- + +## STEP 4 — Post-Release Report + +``` +Release complete: + +✅ Pre-release checks passed +✅ Release prepared and performed +✅ Tag pushed: refs/tags/ +✅ Current dev version: -SNAPSHOT + +Next steps: +- Update CHANGELOG.md with [Unreleased] section for next release +- Announce the release to the team +``` + +--- + +## Rollback + +If the user asks to roll back after a failed release: + +1. Read the "Rollback" section in `docs/release-process.md` +2. Show the rollback commands +3. Ask for explicit confirmation before running any of them +4. For Maven: see **`skills/release/references/maven-release.md` § Rollback** diff --git a/plugins/aem/agentify/skills/agentify/references/repo-agent-templates.md b/plugins/aem/agentify/skills/agentify/references/repo-agent-templates.md new file mode 100644 index 00000000..1becc3a0 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/repo-agent-templates.md @@ -0,0 +1,208 @@ +# Agentify Repo Agent Templates + +Use this reference when `references/phase-2.md` §2.12 (repo-aware helper agents) is in scope. + +## Goal + +Create a small set of repo-local helper agents, implemented under the target repo's root +`agents/` folder, that automate the target repo's most common code flows. These agents +must be **repo-aware**: they should use the real workflow names, docs, commands, +directories, and guardrails discovered earlier in the agentify flow. + +## Rules + +- Do not generate generic "assistant wrappers." If the same agent could be dropped into any + repo with only a noun swap, it is too generic. +- Start from the target repo's real recurring workflows: + - Phase 0/1 findings + - existing runbooks + - `wiki/code-flows.md` + - matching `wiki/code-flow-*.md` pages + - release, test, debug, or module-boundary workflows already documented in the repo +- Keep the set small. Create 3-5 high-value helper agents by default, not a large catalog of thin + wrappers. This is guidance, not a hard limit — create more when the repo has enough distinct, + commonly used workflows to justify it. +- One helper agent should automate one workflow. Do not create catch-all "do everything" + agents. +- Prefer the repo's own vocabulary in agent names. If the repo calls a workflow "backport," + "content sync," or "promote package," use that terminology instead of a generic label. +- Each helper agent must point back to `AGENTS.md` and deeper docs instead of copying full + repo guidance into the agent body. + +## Good Starting Flows + +Use these only when they are genuinely common and can be made repo-specific: + +- explain the repo +- plan a change +- review a change (use `/review-governor`) +- debug a failing build, test, or runtime issue +- work in a specific module or package boundary +- prepare a release-oriented change + +Prefer more specific workflow agents when the repo already has named flows that future agents +will repeatedly need, for example: + +- trace a request through the runtime path +- update a package or content deployment flow +- prepare a migration change +- diagnose CI failures for this repo's pipeline +- follow a release or backport workflow +- maintain the skill catalog (`skill-maintainer`) — create this whenever the repo has a + `skills/` directory; it automates adding/updating skills and keeping all catalog files + (`skills/README.md`, `docs/skills.md`, `AGENTS.md#available-skills`) in sync + +## AI Code Review + +When §2.12 is in scope, offer AI-powered code review as an optional addition for repos where +code review is a recurring, high-value workflow. Use the `/review-governor` skill. + +## Required Repo Facts + +Every generated helper agent should include only the facts relevant to its workflow: + +- repo name and one-line purpose +- primary languages/frameworks and build system +- canonical docs to read first +- exact commands to run for validation +- important directories, modules, or entry points for that workflow +- repo-specific guardrails, immutable contracts, or release constraints +- expected output format for the workflow + +## Recommended File Pattern + +Implement each helper agent under the canonical root-level `agents/` folder: + +```text +agents/ + / + AGENT.md + openai.yaml +``` + +Keep `AGENT.md` focused on the workflow contract and use `openai.yaml` only for lightweight +Codex metadata when Codex is one of the selected tools. + +## Agent Template Guidance + +Each generated helper agent should roughly follow this shape: + +```markdown +--- +name: +description: +tools: Bash, Read, Edit, Write, Glob, Grep +--- + +# + +Use this when: + +Before you start: +- Read `AGENTS.md` +- Read <1-2 repo-specific docs or workflow pages> +- Use `` when relevant + +Repo context: +- Purpose: +- Important paths: ``, `` +- Constraints: + +Workflow: +1. +2. +3. +``` + +The workflow section should: + +- mention real repo paths and commands +- encode expected outputs (plan, findings, patch, release checklist, RCA, etc.) +- call out the repo-specific validation step to run before completion +- stay focused on the single flow + +## Codex Metadata + +When Codex is selected, add `openai.yaml` with minimal UI metadata derived from the +repo-aware agent: + +```yaml +interface: + display_name: "Plan Change" + short_description: "Plan a change using this repository's actual modules and checks" + default_prompt: "Use $plan-a-change to plan a repo-specific change" +policy: + allow_implicit_invocation: false +``` + +Do not put workflow logic in `openai.yaml`. + +## Tool-Local Mirrors + +The root `agents/` folder is canonical. Create tool-local mirrors that point back to it: + +```text +.claude/agents -> ../agents +.codex/agents -> ../agents +.agents/agents -> ../agents +.cursor/agents -> ../agents +.github/agents -> ../agents +``` + +If the repo also has a root-level `skills/` directory, create the corresponding skill mirrors +in the same pass: + +```text +.claude/skills -> ../skills +.codex/skills -> ../skills +.agents/skills -> ../skills +.cursor/skills -> ../skills +.github/skills -> ../skills +``` + +**Symlink safety:** Before running `ln -sf TARGET LINK`, check whether `LINK` already exists +as a symlink. If it does, `ln -sf` will create the new symlink *inside* the existing target +directory rather than replacing it, producing a broken circular link (e.g. `skills/skills`). +Use `ln -sfn TARGET LINK` (the `-n` flag treats an existing symlink-to-directory as a file and +replaces it safely) or remove the stale symlink first with `rm LINK`. + +Do not duplicate or copy agent or skill definitions into these tool-local folders. + +## Agent Registration Rule + +**Applies whenever any repo-local helper agent is created inside a target repo.** + +After writing the canonical files under `agents/`, always register the agents in the exact order +below. + +**Required order:** +1. Update the canonical agent files under `agents/`. +2. Create or update `agents/README.md` with exhaustive per-agent documentation. For each agent + include: purpose, files list, phases or workflow steps, invocation examples, expectations, and + guardrails. `agents/README.md` is the exhaustive catalog — one well-documented section per + agent covering all agents present in the repo, not just the ones changed in this run. +3. Create or update `docs/agents.md` so it covers the full current agent surface in scope, + including both pre-existing agents and agents created or updated in the current run. +4. Update `AGENTS.md` with the **minimal** entry for all agents currently present in the repo. + Document for each one only: + - name + - canonical path under `agents/` + - when to use it + - how to use or invoke it + - one-line purpose and guardrails + Do not copy the exhaustive documentation from `agents/README.md` into `AGENTS.md`. + `AGENTS.md` is the minimal index; `agents/README.md` is the exhaustive catalog. +5. Update `README.md` with a brief human-facing note and point back to `AGENTS.md`. +6. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly + approved in Phase 2, update them so they reflect the current agent catalog and canonical + `agents/` location. Otherwise leave them untouched. +7. Refresh the projection files so they point back to `AGENTS.md#available-agents`. +8. Create or repair the tool-local `agents/` mirrors. + +`AGENTS.md` remains the minimal index. `agents/README.md` is the exhaustive catalog. + +## Alignment Notes + +- If there is a matching prompt under `prompts/repo/`, keep the naming, cited docs, and + workflow terminology aligned between the prompt and the helper agent. +- If the repo already has an equivalent helper agent, update it instead of creating a duplicate. diff --git a/plugins/aem/agentify/skills/agentify/references/repo-type-guidance.md b/plugins/aem/agentify/skills/agentify/references/repo-type-guidance.md new file mode 100644 index 00000000..99f6a0f8 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/repo-type-guidance.md @@ -0,0 +1,57 @@ +# Agentify Repo-Type Guidance + +Reference guidance to apply based on the repo type labels from Phase 0. + +## Packaging Repos (no source code) + +- `AGENTS.md` must explain the build tool's DSL thoroughly — especially if proprietary. + Include a section documenting every DSL keyword, type prefix, and section marker. +- Skip Phase 3 steps 3.1–3.5 (no source code to refactor). +- OSGi config properties and packaging directives should be commented inline in the + build descriptor file. +- For Maven packaging repos: document what each configuration section produces, + what the artifact naming convention is, and which version properties drive the build. + +## Multi-Module Repos (e.g. Maven/Gradle reactor builds) + +- `AGENTS.md` must include a **Module Topology** section: + + | Module | Role | Public API? | Safe to change alone? | + |--------|------|-------------|----------------------| + | `module-a` | Core implementation | Yes | No — others depend on it | + | `module-b` | Tests | No | Yes | + +- `wiki/architecture.md` must include the same Module Topology section. +- `docs/testing.md` must include module-aware test commands (e.g. `mvn test -pl module-a`). +- `docs/release-process.md` must clarify: whole-reactor release vs selected-module release. +- Create per-module `CLAUDE.md` only for unusually complex modules (not for every module). +- Phase 3 step 3.6 (directory structure) is **critical priority** for Multi-module repos. + +## Maven Repos with Even/Odd Versioning + +The current SNAPSHOT version in `pom.xml` encodes the next release: + +| Current pom.xml version | Meaning | Next release | Next SNAPSHOT after release | +|-------------------------|---------|-------------|----------------------------| +| `1.60.7-SNAPSHOT` | In development | `1.60.8` | `1.60.9-SNAPSHOT` | +| `1.60.9-SNAPSHOT` | In development | `1.60.10` | `1.60.11-SNAPSHOT` | + +Rules: +- **Odd patch** = SNAPSHOT in development +- **Even patch** = released artifact + +Always document this strategy in `AGENTS.md` (Versioning Strategy section) and +`docs/release-process.md`. Use `mvn release:prepare` + `mvn release:perform` — never +hardcode version numbers. + +## LLM-App Repos + +- `prompts/` and `evals/` are **high priority** — in Phase 1, only capture the intended + prompt and eval layout and responsibilities in `AGENTS.md`; create or update the actual + `prompts/` and `evals/` directories in Phase 2. +- Keep repo-helper prompts under `prompts/repo/`. Store runtime application prompts separately + under `prompts/system/`, `prompts/tasks/`, and `prompts/templates/`. +- `wiki/architecture.md` must name which model(s) are used and where model selection happens. +- `AGENTS.md` must state where prompts live, how evals are run, and what the expected + eval pass rate is. +- Document prompt versioning strategy (are prompts versioned? in git? in a database?). diff --git a/plugins/aem/agentify/skills/agentify/references/rules-templates.md b/plugins/aem/agentify/skills/agentify/references/rules-templates.md new file mode 100644 index 00000000..6b43e919 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/rules-templates.md @@ -0,0 +1,114 @@ +# Agentify Rules Templates + +Use this reference when Phase 1 creates tool-local quick-reference rule files (§1.11 for +`.claude/rules/`, §1.7 for `.cursor/rules/`, and `.github/rules/` when Copilot is selected). + +## Goal + +Create a set of tool-local quick-reference rule files that project the target repo's conventions +from `AGENTS.md` into the format each tool expects. These files must stay **minimal projections**: +they summarize selected rules for when `AGENTS.md` is not in context — they never become a +second source of truth. + +## Core Rule (Strictly Enforced) + +Every generated rule file must stay short and link back to `AGENTS.md` rather than restating full +convention blocks. The projection file template below implements the required header — follow it +exactly. Never mirror full convention blocks from `AGENTS.md` into rule files. + +## When To Create Each Rule File + +Create only the rule files that match the repo's actual content. Skip files whose subject does +not apply to the target repo. + +| Rule file | Create when | +|-----------|------------| +| `general-coding` | All repos with source code | +| `git-practices` | All repos | +| `java-style` | Repo has Java source | +| `java-testing` | Repo has Java tests | +| `bash-style` | Repo has shell scripts | +| `skill-authoring` | Repo is a skill/agent library or contains `skills/` | + +## File Locations Per Tool + +| Tool | Location | Extension | Notes | +|------|----------|-----------|-------| +| Claude Code | `.claude/rules/` | `.md` | — | +| Cursor | `.cursor/rules/` | `.mdc` | See Cursor front matter section below | +| Copilot | `.github/rules/` | `.md` | Skip a file if `.github/copilot-instructions.md` already covers that topic | + +Create the directory if it does not exist. Do not create all three sets unless all three tools +are selected. Create only the set for the selected tool(s). + +--- + +## Projection File Template + +All rule files follow the same shape regardless of tool or content topic: + +```markdown +# + +**Projection only: never edit this file directly; update `AGENTS.md` first.** + +Canonical source: [AGENTS.md](../../AGENTS.md#) +Projected from `AGENTS.md` as of `` (``). +When repo guidance changes, update `AGENTS.md` first and sync this projection in the same change. + +<5-8 bullet points summarizing the most critical rules for this topic. +Use the repo's real vocabulary. Do not copy full blocks from AGENTS.md.> +``` + +The anchor in the canonical source link should point to the matching `AGENTS.md` section, e.g.: +- `#general-coding-principles` +- `#git-workflow` +- `#java-style` +- `#java-testing` +- `#bash-style` +- `#adding-or-editing-skills` + +--- + +## Per-Rule Content Guidance + +Summarize 5–8 bullets per rule file. Key topics by file: + +| Rule file | Topics to summarize | +|-----------|-------------------| +| `general-coding` | Scope: apply standards to new code only — match existing file style for pre-existing code; functional over OOP (stateless pure functions, no input mutation); DRY/KISS/YAGNI; single-purpose functions — no flag/mode parameters that switch behavior; no fallbacks unless explicitly requested — fix root causes; error handling: explicit throws, specific types, actionable messages with context; strict typing everywhere; comments in English only | +| `git-practices` | Commit format: `WORK-ID : brief description` (lowercase, present tense, one line); PR body: always add `Co-Authored-By: ` at the end — Claude → `Co-Authored-By: Claude `, Copilot → `Co-Authored-By: GitHub Copilot `, Cursor → `Co-Authored-By: Cursor `, Codex → `Co-Authored-By: OpenAI Codex `; never `git add .` or `git add -A` — use specific files or `git add -u`; always show what will be staged/committed/pushed and wait for user approval before any git write operation; non-interactive diff: `git --no-pager diff`; use `--force-with-lease` instead of `--force`; before pushing review fixes, verify PR is still OPEN (`gh pr view --json state --jq '.state'`) | +| `java-style` | No static imports, no wildcard imports, no inline package-qualified names in new code; for existing files, match the file's existing import style exactly — never add static imports to satisfy the rule; Javadoc on all new public methods; parameter validation in all new public methods; logging: parameterized `{}` — never string concatenation; no flag parameters that switch method behavior; prefer Java 17 features: records for immutable data, sealed classes, pattern-matching instanceof, text blocks, switch expressions, var | +| `java-testing` | JUnit 4 preferred for AEM Mocks-based tests (JUnit 5 also supported on AEM 6.5.6+ and AEMaaCS); test class name: `MyClassTest` suffix; method names camelCase only — never snake_case; no static imports in new test classes — fully qualified `Assert.assertEquals()`, `Mockito.when()`; add class-level Javadoc linking to the class under test; match existing file's assertion/mocking style for new methods added to existing test files; prefer real objects over mocks; 90%+ line/branch coverage; external storage tests: clean in `@Before` AND `@After`, use unique test-scoped paths/keys | +| `bash-style` | Function names: `lowercase_underscores`, start with action verbs (`execute_`, `verify_`, `get_`), never camelCase or leading underscore; local variables: `lowercase_underscores`; constants/env vars: `UPPER_UNDERSCORES`; arithmetic under `set -e`: use `var=$((var + 1))` not `((var++))`; always quote variables; error capture: `set +e; cmd; rc=$?; set -e`; non-interactive flags on all commands | +| `skill-authoring` | Canonical location: `skills//` only — never edit tool-local mirror folders; SKILL.md under 500 lines; required frontmatter: `name`, `description`; use `$ARGUMENTS` for user input; explicitly link all supporting files so Claude knows they exist; keep skills generic — no hardcoded repo paths, ticket IDs, or usernames; scripts go under `scripts/`, reference with `${CLAUDE_SKILL_DIR}/scripts/`; use `context: fork` + `agent:` for isolated task execution; register in marketplace and README; add a final step to run `/simplify` on all generated files | + +--- + +## Cursor `.mdc` Front Matter + +Cursor rule files (`.cursor/rules/*.mdc`) should include Cursor-specific front matter: + +```yaml +--- +description: +globs: +alwaysApply: false +--- +``` + +Use `alwaysApply: true` only for repo-wide rules like `git-practices` and `general-coding`. +Use `alwaysApply: false` with a specific glob for language-specific rules like `java-style`. + +--- + +## Verification And Alignment + +Rule files are projections, not registered artifacts. No marketplace or catalog entry needed. + +After writing rule files: +1. Verify every generated rule file has the projection header and audit line. +2. Confirm the canonical source link resolves to a real `AGENTS.md` section. +3. Refresh `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md` if they reference + these rule files by name — ensure the references are accurate. +4. Do not add rule file content to `AGENTS.md`. The rules flow only from `AGENTS.md` outward. diff --git a/plugins/aem/agentify/skills/agentify/references/skills-templates.md b/plugins/aem/agentify/skills/agentify/references/skills-templates.md new file mode 100644 index 00000000..aa8d56a7 --- /dev/null +++ b/plugins/aem/agentify/skills/agentify/references/skills-templates.md @@ -0,0 +1,193 @@ +# Agentify Skill Templates + +Use this reference when `references/phase-2.md` §2.12 (repo-local skills) is in scope, or when +any agentify phase creates a skill inside the target repo. The `/release` skill has its own +dedicated template in `references/release-skill-template.md` — use that instead for release skills. + +## Goal + +Create a small set of repo-local skills, implemented under the target repo's `skills/` folder, +that encode the target repo's most common, repeatable workflows. These skills must be +**repo-aware**: they should use the real workflow names, docs, commands, directories, and guardrails +discovered earlier in the agentify flow. + +## Rules + +- Do not generate generic "assistant wrappers." If the same skill could be dropped into any repo + with only a noun swap, it is too generic. +- Start from the target repo's real recurring workflows: + - Phase 0/1 findings + - existing runbooks + - `wiki/code-flows.md` and matching `wiki/code-flow-*.md` pages + - release, test, debug, migration, or module-boundary workflows already documented in the repo +- Keep the set small. Create 1-3 high-value skills by default, not a large catalog of thin + wrappers. `agentify` already creates the `/release` skill via `release-skill-template.md` when + applicable — count that in the set. +- One skill encodes one workflow. Do not create catch-all "do everything" skills. +- Prefer the repo's own vocabulary in skill names. If the repo calls a flow "backport," + "content sync," or "promote package," use that terminology. +- Keep `SKILL.md` under 500 lines. Move bulky detail into `references/` files. +- Each skill must point back to `AGENTS.md` and deeper docs instead of copying full repo + guidance inline. +- No hardcoded repo paths, ticket IDs, or usernames in skill content — skills must remain + generic and reusable if extracted. + +## Good Starting Flows + +Use these only when they are genuinely common and can be made repo-specific: + +- cut a release (→ use `release-skill-template.md` for this one) +- debug a failing build, test, or CI pipeline step +- backport a fix to a maintenance branch +- prepare a migration change +- validate or deploy a package +- work within a specific module boundary + +## Required Repo Facts + +Every generated skill should include only the facts relevant to its workflow: + +- repo name and one-line purpose +- primary languages/frameworks and build system +- canonical docs to read first +- exact commands to run for validation +- important directories, modules, or entry points for that workflow +- repo-specific guardrails, immutable contracts, or release constraints + +## Recommended File Pattern + +```text +skills/ + / + SKILL.md + references/ ← optional; detailed docs linked from SKILL.md + scripts/ ← optional; helper scripts +``` + +## SKILL.md Template + +```markdown +--- +name: +description: > + +tools: Bash, Read, Edit, Write, Glob, Grep +--- + +# + + + +## When To Use + + + +## Before You Start + +- Read `AGENTS.md` +- Read `<1-2 repo-specific docs or runbook sections>` +- Use `` to verify your environment when relevant + +## Repo Context + +- Purpose: +- Important paths: ``, `` +- Constraints: + +## Workflow + +1. +2. +3. +``` + +The workflow section should: +- mention real repo paths and commands +- encode expected outputs (plan, findings, patch, release checklist, RCA, etc.) +- call out the repo-specific validation step to run before completion +- stay focused on the single workflow + +## `references/` Files + +When a skill needs reference material — patterns, checklists, command references — put them under +`skills//references/` and link them explicitly from `SKILL.md`: + +```markdown +## Supporting Files + +| File | Purpose | Load when | +|------|---------|-----------| +| [references/patterns.md](references/patterns.md) | ... | When ... | +``` + +Do not inline bulky reference content in `SKILL.md` — that is what pushes it past 500 lines. + +## `openai.yaml` (Optional) + +When Codex is one of the selected tools, add `openai.yaml` with minimal metadata: + +```yaml +interface: + display_name: "" + short_description: "" + default_prompt: "Use / to " +policy: + allow_implicit_invocation: false +``` + +Do not put workflow logic in `openai.yaml`. + +## Skill Registration Rule + +**Applies whenever any skill is created inside a target repo** (currently: the `/release` skill in +`2.6`, but applies to any future skill agentify creates). + +After writing the canonical files under `skills/`, always register the skills in the exact order +below. This registration pass must cover the full current skill set in scope for the repo section +you are updating, not just the skills created in the current change. + +**Required order:** +1. Update the canonical skill files under `skills/`. +2. Create or update `skills/README.md` with exhaustive per-skill documentation. For each skill + include: purpose, trigger phrases, argument usage, workflow steps, supporting files, and + constraints. `skills/README.md` is the exhaustive catalog — one well-documented section per + skill, covering all skills present in the repo, not just the ones changed in this run. +3. Create or update `docs/skills.md` so it covers the full current skill surface in scope, + including both pre-existing skills and skills created or updated in the current run. +4. Update `AGENTS.md` with the **minimal** entry for all skills currently present in scope. + Document for each one only: + - name + - canonical path under `skills/` + - when to use it + - how to use or invoke it + - one-line purpose and guardrails + Do not copy the exhaustive documentation from `skills/README.md` into `AGENTS.md`. + `AGENTS.md` is the minimal index; `skills/README.md` is the exhaustive catalog. +5. Update `README.md` with a brief human-facing note and point back to `AGENTS.md`. +6. If `docs/runbooks.md` and/or `wiki/architecture.md` already exist, or were explicitly + approved in Phase 2, update them so they reflect the current skill set and canonical `skills/` + location. Otherwise leave them untouched. +7. Refresh the projection files (`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`) + so they point back to `AGENTS.md#available-skills` and `skills/README.md`. +8. Create or repair the tool-local `skills/` mirrors: + + ```text + .claude/skills -> ../skills + .codex/skills -> ../skills + .agents/skills -> ../skills + .cursor/skills -> ../skills + .github/skills -> ../skills + ``` + + Use `ln -sfn ../skills ` (note `-n`) so that re-running is safe even if the symlink + already exists — `-n` treats an existing symlink-to-directory as a file and replaces it + rather than creating a nested `skills/skills` entry inside the target. + +`AGENTS.md` is the minimal index. `skills/README.md` is the exhaustive catalog. + +## Alignment Notes + +- If the repo already has an equivalent skill, update it instead of creating a duplicate. +- If a matching prompt under `prompts/repo/` exists for the same workflow, keep the naming, + cited docs, and terminology aligned between the prompt and the skill.