docs(framework): update readme positioning#333
Draft
alexsoyes wants to merge 17 commits into
Draft
Conversation
* docs(framework): add dominance checks to review and rules Dominance issues were easy for agents to miss when a weaker rule, criterion, or documentation statement was already covered, overridden, or invalidated by a stronger element. This adds the check at the global context, rule-generation, reviewer, and review-template levels. * docs(framework): reduce dominance check duplication Keep the concise dominance rule in global and rule-authoring surfaces while leaving the detailed case breakdown to the reviewer. Validation now states the shared check without reimplementing reviewer classification. * docs(framework): separate global and rule dominance checks Keep the general dominance reminder and reviewer taxonomy separate from rule-generation specifics. Rule authoring and validation now only check for duplicate, weaker, or contradictory rule bullets. * docs(framework): prefer intention-revealing names Naming guidance belongs in the global project context because it applies across artifacts. This keeps the rule concise and avoids duplicating it in domain-specific rule generation flows. * docs(aidd-context): validate rules against shared contracts Rule validation should apply the rule-authoring and tool-path contracts instead of restating individual rule checks. The test now has a single outcome sentence rather than multiple bullet assertions. * docs(aidd-dev): align dominance wording with review role The reviewer should report parallel elements rather than describe adding behavior. This keeps the dominance check phrased for read-only review while preserving the same taxonomy.
Required check "lefthook (framework-local checks)" (next.json ruleset) is published only by validate.yml, whose pull_request/push filter was [main]. PRs targeting next never fired it, so the required status stayed "Expected — Waiting for status" forever, deadlocking merges (e.g. #307). Add next to both push and pull_request branch filters. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(framework): add markdown link checker * fix(scripts): exempt template scaffold placeholder links 01-plan's plan-template.md / phase-template.md link to ./plan.md and ./phase-N.md — files the skill emits next to the generated output at runtime (see actions/04-plan.md), never committed to the repo. The checker flagged them as broken. Extend the existing asset-template branch: a dot-relative target in a *-template.md that resolves nowhere is an intentional placeholder for a generated sibling, so treat it as ignored rather than broken. The assets/templates fallback (used by 02-project-memory) is unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(aidd-ui): scaffold alpha plugin (0.1.0-alpha.0) Add aidd-ui as a new plugin with a single smoke-test skill (01-hello). Registered in marketplace.json (recommended: false) and release config; alpha status is conveyed by the 0.1.0-alpha.0 version in plugin.json. Lives on a dedicated branch off next, so it is not public until it graduates to main. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(aidd-ui): mark alpha / not-ready across surfaces Add prominent alpha warnings to the plugin README, the homepage plugins table, and the marketplace and plugin descriptions so the not-ready status is unmistakable. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Dependabot had no target-branch, so its PRs defaulted to main. main only takes the weekly promotion PR and the auto-merged Release PR (RELEASE.md), so dep updates landing there cut off-cycle releases (js-yaml bump shipped v5.0.3 mid-week). Point both ecosystems at next so updates batch into the weekly release like all other work. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New skill aidd-vcs:00-repo-init: init a project's repository (git init, default branch, CONTRIBUTING.md, bootstrap commit) and, on request, create the remote and push. Provider- and mechanism-agnostic: host + reach (CLI, MCP, or API) resolved from VCS memory or environment, main as default-branch fallback. No hardcoded provider or fixed mechanism. Conforms to the skill-authoring contract (R1-R13 + action anatomy). Co-authored-by: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* ci(deps): bump actions/checkout from 6.0.3 to 7.0.0 (#321) Bumps [actions/checkout](https://github.com/actions/checkout) from 6.0.3 to 7.0.0. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@df4cb1c...9c091bb) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * docs(framework): unify change taxonomy into one source of truth The same change taxonomy (kind -> where it ships) was re-spelled across branch prefix, commit type, label, and the board "Work Type" field, and the four drifted. A maintainer got lost finding routing info. Make aidd_docs/memory/vcs.md the single canonical home: one dense table (kind, prefix, commit type, triage label, next/main) plus a strict routing rule. CONTRIBUTING and RELEASE now link it instead of restating it; the inline label table is gone. Trim labels 11 -> 8 (drop help wanted, npm, github-actions) and stop dependabot re-adding the dropped ecosystem labels. Add a Project 8 board playbook + label-delete note to MAINTAINERS, and fix its stale "Work Type" reference. Routing is derived from the branch prefix, never a label or board field. Spec + plan recorded under aidd_docs/. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(aidd-vcs): derive PR base from branch prefix, auto-apply triage label The pull-request action resolved the base from origin/HEAD against a candidate list (main/master/develop/staging) that omitted `next`, so a `feat/*` PR targeted `main`. Resolve the base from the head branch's prefix via the project-memory routing table first, falling back to the old detection. After opening, apply the prefix's triage label when it exists. Stays generic: reads project memory, never hardcodes `next`. Also fix the stale `aidd_docs/` -> `docs/` prefix in the branch template. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(framework): make the routing table an actionable guide Reframe the canonical Types table as "I want to… → I do…": add an Issue template column and a one-line board Status flow, so a contributor finds their row and reads off branch, label, and PR target in one glance. Still the single source of truth — no new table, no duplication. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…326) The skill's transversal rules still described base detection from repo state only, omitting the prefix-based routing and auto-labelling the action now performs. Bring the SKILL.md contract in line: base resolves from the branch prefix via project memory (fallback to repo state), and the matching triage label is applied after opening. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(aidd-refine): align 02-05 skills with skill contract Bring challenge, condense, shadow-areas and fact-check skills to the 04-skill-generate contract and concise, plain language. - SKILL.md routers: `## Actions` header, plain-path references/assets, drop empty None. sections - actions: singular Input/Output, no pipeline-variable notation, bold process labels, no frozen data blocks - move challenge report skeleton to a new assets/report-template.md - extract fact-check output-discipline into a cited reference - shorten the four skill descriptions to two lines Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(aidd-refine): tighten tests and trim duplication Follow-up from a headless skill-by-skill audit against the 04-skill-generate contract. - shadow-areas: collapse redundant Test bullets (6/8/6 -> 5/7/4), one-line Outputs, fix 01-detect handoff (route via 03-diff before 02-render-report when a prior report exists) - challenge: fix Test deal-breaker/confidence rule to match the rubric, drop transversal rules that restated the action - condense: drop persistence-duplicate process step, tighten tests, lean the router (no inline examples) - fact-check: shorten 03-report Output, dedupe caching guidance Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(aidd-refine): drop punctuation dashes for concise prose Replace em-dash-style " - " punctuation with commas, colons, or parentheses across skill bodies, actions, and references. Keep title headers and the literal "(unverified - no source found)" output marker. Also fix severity-rubric "Definition rule" -> "Decision rule" label. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(aidd-refine): harden condense and fact-check fidelity Found by the behavioral eval harness running the skills for real. - fact-check: add a `refuted` verdict (a source contradicts the claim, distinct from "no source found"); emit the unverified marker verbatim; forbid leaking the verification method (commands, "by inspection"); remove "cascade exhausted ..." from the report template, which leaked a forbidden word the discipline bans - condense: 01-condense must emit the exact `Condense: ON (<level>).` line, since 02-stats and the hook parse it from the transcript * test(aidd-refine): add behavioral skill-eval harness Runs each refine skill for real through a headless `claude -p` in an isolated temp project (the worktree skill installed under a unique name, so the local copy runs, never a stale global plugin). Deterministic checks by default; `--judge` adds an LLM grader for fuzzy outcomes. Local / opt-in only (metered, no `claude` in CI), so not a CI gate. Covers shadow-areas, fact-check, condense, challenge; brainstorm is interactive and out of scope. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…esign (#314) Collapse the SDLC agent trio (planner/implementer/reviewer) into two leaf agents, executor + checker, with the 00-sdlc orchestrator owning planning itself. Enforce recipe-not-spawn: only the orchestrator spawns, recipe skills focus on themselves and never name other skills or the SDLC. - executor runs 02-implement, checker runs 05-review (embedded checklist). - executor never holds 01-plan (structural immutability). - 05-review gains a relevancy axis (fit/conform/rot) into one review.md. - commit, pull-request, and assert defer to project memory (vcs.md, coding-assertions.md) over bundled defaults; ship stops dictating the commit format. - pull-request is fully VCS-tool-agnostic. - all flow skills renormalized to the skill-authoring contract; orphan assets and a leaked user-stories WIP duplicate removed. Net +673/-1269. Refs #253. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…#328) When the user asks to delete or remove code, the refactor skill is now a trigger target and routes straight to the cleanup action. The cleanup action sweeps for orphaned references a deletion leaves behind, so removals also clean up imports, tests, docs, and config that pointed at the deleted symbol. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(aidd-context): unify and trim agent instruction template - Merge best rules from CLAUDE.md and the project-memory AGENTS.md template into one focused set - Cut aspirational/duplicate lines (goal-driven, redundant simplicity/anti-sycophancy/sureness restatements) - Keep high-impact rules: evidence-over-assertion, quote-shortest-line, dedup meta-rule, intention-revealing names - Align root CLAUDE.md: reference parent for shared behavior, keep framework specifics Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): sync CLAUDE.md with agent template, tighten rules - Make CLAUDE.md a true instance of the project-memory AGENTS.md template (same rules and structure; only title, placement bullet, and filled memory block differ) - Push CLAUDE.md-only rules up into the template: surface tradeoffs, solve own issues first, check it is good practice, less-is-more folded into Communication - Add focus rule: stay focused, not scattered (keeps freedom, no scope-creep framing) - Drop the anthropomorphize line; ban em-dashes alongside emoji Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): apply reviewer fixes to agent template rules - Dedup anti-sycophancy (3 bullets into 1) and brevity (2 into 1) - Add output-token rule: no preamble or recap - Operationalize focus: flag unrelated issues, detour only if blocking - Clarify the good-practice check Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): swap dedup meta-rule for a no-guessing rule - Add: don't guess APIs/signatures/flags/behavior, read source or docs first (prevents hallucination, the top dumb-failure mode) - Remove: the dedup meta-rule (off the runtime objectives; belongs in a standards doc) - Keep intention-revealing names and the first-message greeting Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): scan-first response style and clarify-scope rule - Rewrite brevity rule: telegraphic scan-first style for chat (arrows, fragments), normal prose for docs, full prose for security/irreversible/order-dependent - Extend no-preamble rule to ban trailing next-step padding - Add: ask one sharp question to pin down scope before an ambiguous or expensive build Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): add parallel-execution rules to agent template - Batch independent operations in one pass, not one at a time (full test suite, not test by test) - Fan out independent subtasks to parallel subagents Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): fix rule tensions and add next-step output rule - Merge simple-beats-clever into surgical changes - Make exceeding the ask an explicit exception, not the default - Gate subagent fan-out to genuinely large or parallelizable work - Broaden the scan-first clarity exception to any nuanced explanation - Reframe output rule: no suggestion menus, but always state the single next action Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): restore dedup rule, soften fan-out to orchestrators - Restore the single-source-of-truth rule removed earlier (downstream projects keep it) - Soften fan-out: only when you own the overall flow, per docs/ARCHITECTURE.md spawning boundary - Drop the test-suite example from the batch rule Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): bold rule heads and tighten wording - Bold the lead directive of each rule for scannability - Trim wording where it loses no meaning (notably the dedup rule) - Memory block unchanged (tooling-managed, must stay live) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): clarify escalation, knowledge, and tradeoff rules - Solve-your-own-issues: try yourself first, escalate to the human (names the target) - Drop the vague good-practice clause; keep don't-assume-knowledge-is-current - Surface tradeoffs and evaluate their impact (replaces vague confusion) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): allow commit/push inside authorizing flows Agents running inside an authorizing flow (e.g. the SDLC) may commit/push; the default still blocks unprompted commits. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): simplify commit rule exception for allowed agents Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): revert commit rule to simple user-asks default Drop the vague allowed-to escape hatch; authorized flows grant their own agents in their own definitions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 What & why
Updates the README headline copy to the requested French framework positioning.
🛠️ How it works
Replaces the previous two-line positioning block with the new single headline in README.md. The repository pre-commit hook also refreshed generated README counts.
🧪 How to verify
git diff origin/next...docs/readme-positioning -- README.md.Generated README counts changed from
41 skillsto40 skills, andaidd-pmfrom5 skillsto4 skillsduring the pre-commit sync.✅ I certify