paralleldrive · ericelliott · Apr 17, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-04-15
+
+### Breaking Changes
+- **`/aidd-functional-requirements` moved** to **`/aidd-requirements`** with the directory `ai/skills/aidd-requirements/`. Update agent rules, README-style links, and any paths that pointed at `aidd-functional-requirements`.
+
+### Added
+- `/aidd-rtc` skill — Reflective Thought Composition for structured, higher-quality reasoning
+- `/aidd-parallel` skill — `/aidd-fix` delegation prompts and parallel sub-agent coordination (dependency ordering, rebase constraint)
+- `/aidd-pipeline` skill — run a sequential pipeline from a markdown task list via isolated sub-agents (Task tool)
+- `/aidd-pr` skill — triage PR review threads, resolve addressed feedback, delegate remaining work to sub-agents
+- `/aidd-riteway-ai` skill — Riteway AI `.sudo` prompt evals for multi-step flows that use tools (with unit tests)
+- `/aidd-upskill` skill — authoring and upskilling AIDD skills; reference `validate-skill` implementation, tests, and docs
+- `/aidd-changelog` skill — write and maintain release changelog entries focused on consumer impact
+- README skills list — added entries for all 7 new skills
+- **`build:validate-skill`** npm script — compile the upskill validator via Bun
+- **`test:ai-eval:upskill`** npm script — run Riteway AI evals under `ai-evals/aidd-upskill/`
+- GitHub Actions — AI eval workflow on a **daily cron** (1 run), **Slack** notification to `#ai-test-reports` on failure, restricted to **`main`**
+
+### Changed
+- **`test:ai-eval`** — default `--runs` reduced from **4** to **1** (matches cron and lowers local/CI cost)
+- `docs/scaffold-authoring.md` — clearer guidance for CLI operations during scaffold authoring
+- `/aidd-sudolang-syntax` skill **Semantic pattern matching** documented
+
+
+### Fixed
+- `aidd-please`, `aidd-task-creator`, `aidd-review`, `aidd-churn` now use `/aidd-rtc --compact` to save thinking tokens and improve thinking quality
+- Stale **`/aidd-functional-requirements`** references across skills and docs updated to **`/aidd-requirements`**
+
+## [3.1.0] - 2026-03-30
+
+### Fixed
+- `npx aidd create` — scaffold downloads from GitHub prefer **`gh auth token`**, then **`GITHUB_TOKEN`** / **`GH_TOKEN`**; `Authorization` is attached only for GitHub hosts (`api.github.com`, `github.com`, `codeload.github.com`); documented `gh auth login` in README and scaffold authoring guide (#176)
+
+### Changed
+- `aidd-react` skill — **Review** note on stable React hooks ordering
+
 ## [3.0.0] - 2026-03-29
 
 ### Added

diff --git a/README.md b/README.md
@@ -461,6 +461,7 @@ Skills are reusable agent workflows that extend AIDD with specialized capabiliti
 
 - **[/aidd-agent-orchestrator](ai/skills/aidd-agent-orchestrator/README.md)** — Coordinates specialized agents for software development tasks. Use when routing requests to the right agent or coordinating multi-domain tasks.
 - **[/aidd-autodux](ai/skills/aidd-autodux/README.md)** — Create and transpile Autodux Redux state management dux objects. Use when building Redux state management, defining reducers, action creators, or selectors.
+- **[/aidd-changelog](ai/skills/aidd-changelog/README.md)** — Write and maintain release changelog entries focused on consumer impact. Use when preparing a release or auditing unreleased changes.
 - **[/aidd-churn](ai/skills/aidd-churn/README.md)** — Hotspot analysis: run `npx aidd churn`, interpret the ranked results, and recommend specific files to review or refactor with concrete strategies. Use before a PR review, before splitting a large diff, or when asked to identify the highest-risk code in a codebase.
 - **[/aidd-ecs](ai/skills/aidd-ecs/README.md)** — Enforces @adobe/data/ecs best practices. Use when working with ECS components, resources, transactions, actions, systems, or services.
 - **[/aidd-error-causes](ai/skills/aidd-error-causes/README.md)** — Structured error handling with the error-causes library. Use when throwing errors, catching errors, defining error types, or implementing error routing.
@@ -474,10 +475,15 @@ Skills are reusable agent workflows that extend AIDD with specialized capabiliti
 - **[/aidd-log](ai/skills/aidd-log/README.md)** — Document completed epics in a structured changelog with emoji categorization. Use after completing a significant feature or epic.
 - **[/aidd-namespace](ai/skills/aidd-namespace/README.md)** — Ensures types and related functions are authored in a modular, discoverable, tree-shakeable pattern. Use when creating types, refactoring type folders, or defining schemas.
 - **[/aidd-observe](ai/skills/aidd-observe/README.md)** — Enforces Observe pattern best practices from @adobe/data/observe. Use when working with observables, reactive data flow, or service Observe properties.
+- **[/aidd-parallel](ai/skills/aidd-parallel/README.md)** — Generate `/aidd-fix` delegation prompts for a list of tasks and dispatch them to sub-agents in dependency order. Use when fanning work out across multiple parallel agents.
 - **[/aidd-please](ai/skills/aidd-please/README.md)** — General AI assistant for software development projects. Use for general assistance, logging, committing, and proofing tasks.
+- **[/aidd-pipeline](ai/skills/aidd-pipeline/README.md)** — Run a sequential pipeline of tasks defined in a markdown file, delegating each step to an isolated sub-agent. Use when executing a multi-step task list automatically.
+- **[/aidd-pr](ai/skills/aidd-pr/README.md)** — Triage PR review comments, resolve already-addressed threads, and delegate remaining fixes to sub-agents. Use when a PR has open review comments that need to be triaged or fixed.
 - **[/aidd-product-manager](ai/skills/aidd-product-manager/README.md)** — Plan features, user stories, user journeys, and conduct product discovery. Use when building specifications, journey maps, story maps, or personas.
 - **[/aidd-react](ai/skills/aidd-react/README.md)** — Enforces React component authoring best practices. Use when creating React components, binding components, or working with React UI patterns.
 - **[/aidd-review](ai/skills/aidd-review/README.md)** — Conduct thorough code reviews focusing on quality, security, test coverage, and adherence to project standards. Use when reviewing code, pull requests, or completed epics.
+- **[/aidd-riteway-ai](ai/skills/aidd-riteway-ai/README.md)** — Write correct Riteway AI prompt evals (`.sudo` files) for multi-step agent flows that involve tool calls. Use when writing or testing agent skill evals.
+- **[/aidd-rtc](ai/skills/aidd-rtc/README.md)** — Reflective Thought Composition: structured multi-stage reasoning to improve answer quality. Use when quality of reasoning matters more than speed.
 - **[/aidd-service](ai/skills/aidd-service/README.md)** — Enforces asynchronous data service authoring best practices. Use when creating front-end or back-end services, service interfaces, or data flow patterns.
 - **[/aidd-stack](ai/skills/aidd-stack/README.md)** — Tech stack guidance for NextJS + React/Redux + Shadcn UI features. Use when implementing full stack features or choosing architecture patterns.
 - **[/aidd-structure](ai/skills/aidd-structure/README.md)** — Enforces source code structuring and interdependency best practices. Use when creating folders, moving files, adding imports, or planning module architecture.
@@ -486,6 +492,7 @@ Skills are reusable agent workflows that extend AIDD with specialized capabiliti
 - **[/aidd-tdd](ai/skills/aidd-tdd/README.md)** — Systematic test-driven development with proper test isolation. Use when implementing code changes, writing tests, or when TDD process guidance is needed.
 - **[/aidd-timing-safe-compare](ai/skills/aidd-timing-safe-compare/README.md)** — Security rule for timing-safe secret comparison using SHA3-256 hashing. Use when reviewing or implementing secret comparisons, token validation, or API key checks.
 - **[/aidd-ui](ai/skills/aidd-ui/README.md)** — Design beautiful and friendly user interfaces and experiences. Use when building UI components, styling, animations, accessibility, or responsive design.
+- **[/aidd-upskill](ai/skills/aidd-upskill/README.md)** — Create and review AIDD skills following a consistent authoring standard. Use when creating, reviewing, or refactoring skills in `ai/skills/` or `aidd-custom/skills/`.
 - **[/aidd-user-testing](ai/skills/aidd-user-testing/README.md)** — Generate human and AI agent test scripts from user journey specifications. Use when creating user test scripts or validating user journeys.
 
 ## 📁 AI System Structure

diff --git a/ai/commands/aidd-changelog.md b/ai/commands/aidd-changelog.md
@@ -0,0 +1,10 @@
+---
+description: Write and maintain CHANGELOG.md entries that help users understand what changed in a release.
+---
+# 📋 /aidd-changelog
+
+Load and execute the skill at `ai/skills/aidd-changelog/SKILL.md`.
+
+Constraints {
+  Before beginning, read and respect the constraints in /aidd-please.
+}
diff --git a/ai/commands/index.md b/ai/commands/index.md
@@ -4,6 +4,12 @@ This index provides an overview of the contents in this directory.
 
 ## Files
 
+### 📋 /aidd-changelog
+
+**File:** `aidd-changelog.md`
+
+Write and maintain CHANGELOG.md entries that help users understand what changed in a release.
+
 ### 📊 /aidd-churn
 
 **File:** `aidd-churn.md`

diff --git a/ai/skills/aidd-changelog/README.md b/ai/skills/aidd-changelog/README.md
@@ -0,0 +1,14 @@
+# aidd-changelog
+
+Keeps `CHANGELOG.md` accurate and useful — focused on what changed for consumers, not implementation detail.
+
+## Usage
+
+```
+/aidd-changelog analyze [since-tag]   — draft changelog entries from git history
+/aidd-changelog update                — write the approved entries to CHANGELOG.md
+```
+
+## Why
+
+Changelog entries written from commit messages default to implementation noise. This skill rewrites them from the consumer's perspective: what capability was added, what broke, what behavior changed — nothing else.
diff --git a/ai/skills/aidd-changelog/SKILL.md b/ai/skills/aidd-changelog/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: aidd-changelog
+description: >
+  Write and maintain CHANGELOG.md entries that help users understand what changed in a release.
+  Use when updating the changelog, preparing a release, or auditing unreleased changes.
+---
+
+# aidd-changelog
+
+import /aidd-log
+import /aidd-rtc
+import references/guidelines.md
+
+Act as a senior software engineer writing release notes for other developers.
+The changelog is for **consumers of the package**, not the team that built it.
+
+Constraints {
+  Changelogs are for humans, not machines.
+  There should be an entry for every single version.
+  The same types of changes should be grouped.
+  Versions and sections should be linkable.
+  The latest version comes first.
+  The release date of each version is displayed.
+}
+
+TypesOfChanges {
+  Added
+  Changed
+  Deprecated
+  Removed
+  Fixed
+  Security
+}
+
+For what to omit, see `/aidd-log` (same rules apply: no config changes, no file moves, no test changes, no meta-work, no internal refactoring).
+
+## Process
+
+### /aidd-changelog analyze
+
+analyzeChanges(sinceTag) => changeSet {
+  1. Run `git log <sinceTag>..HEAD --oneline` to collect commits
+  2. For each commit, classify types of changes |> filter by scoping and omit rules from references/guidelines.md and /aidd-log
+  3. Group related commits into single entries by shared user benefit
+  4. /aidd-rtc --compact
+  5. Write each entry from the consumer's perspective — benefit, not mechanism
+  6. Present the proposed changelog block to the user for review
+}
+
+### /aidd-changelog update
+
+updateChangelog(changeSet) {
+  1. Read existing CHANGELOG.md
+  2. Prepend the approved changeSet as a new versioned release block
+  3. Write the updated file
+}
+
+Commands {
+  /aidd-changelog analyze [sinceTag] — classify commits and draft changelog entries (thinking)
+  /aidd-changelog update             — write the approved entries to CHANGELOG.md (effect)
+}
diff --git a/ai/skills/aidd-changelog/references/guidelines.md b/ai/skills/aidd-changelog/references/guidelines.md
@@ -0,0 +1,48 @@
+# Changelog Guidelines
+
+## What to Write
+
+Each entry answers: **what does this mean for someone using the tool?**
+
+Write the benefit or impact, not the implementation:
+
+```
+✅ `aidd-please`, `aidd-review` now use `/aidd-rtc --compact` to save thinking tokens
+❌ replace inline RTC emoji pipelines with `import /aidd-rtc` and `/aidd-rtc --compact`
+
+✅ `/aidd-upskill` skill — authoring and upskilling AIDD skills
+❌ `/aidd-upskill` — restore `/aidd-rtc --compact` in both pipelines; add `import /aidd-rtc`
+
+✅ Stale `/aidd-functional-requirements` references updated to `/aidd-requirements`
+❌ fix(skills): update stale aidd-functional-requirements references to aidd-requirements
+```
+
+## Scoping Rules
+
+```
+(skill is new in this release)     => ### Added only; never ### Changed or ### Fixed
+(behavior changed for consumers)   => ### Changed
+(bug existed in a prior release)   => ### Fixed
+(consumer must update their code)  => ### Breaking Changes
+(internal-only change)             => omit
+```
+
+## Consolidation
+
+Group related changes into a single entry when the user benefit is the same:
+
+```
+✅ `aidd-please`, `aidd-task-creator`, `aidd-review`, `aidd-churn` now use `/aidd-rtc --compact`
+❌ four separate bullet points describing each skill individually
+```
+
+## Section Order
+
+```
+### Breaking Changes   ← consumer action required
+### Added              ← new capabilities
+### Changed            ← existing behavior that works differently
+### Fixed              ← bugs that were broken for consumers
+### Deprecated         ← things being phased out
+### Removed            ← things that are gone
+```
diff --git a/ai/skills/aidd-churn/SKILL.md b/ai/skills/aidd-churn/SKILL.md
@@ -20,13 +20,15 @@ Competencies {
   PR scoping (splitting diffs by risk profile)
 }
 
+import /aidd-rtc
+
 Constraints {
   Always run the CLI before making recommendations — never guess at hotspots
   Read README.md (colocated) for metric definitions, score formula, and interpretation ranges
   Name specific files; explain which signal (LoC, churn, complexity, or density) is driving each score
   For each recommendation, propose a concrete strategy — not generic advice
   Communicate as friendly markdown prose — not raw SudoLang syntax
-  (Cx > 9 | LoC > 400 | density < 35%) => check whether the file was below the threshold before the current diff (i.e. the diff pushed it over). If so, analyze refactor paths — show your work: 🎯 restate |> 💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond. If a refactor path drops the composite score (LoC × churn × Cx) by >15% (e.g. by splitting up large files), recommend it before merging; otherwise report findings.
+  (Cx > 9 | LoC > 400 | density < 35%) => check whether the file was below the threshold before the current diff (i.e. the diff pushed it over). If so, analyze refactor paths using /aidd-rtc --compact. If a refactor path drops the composite score (LoC × churn × Cx) by >15% (e.g. by splitting up large files), recommend it before merging; otherwise report findings.
 }
 
 ## Step 1 — Collect hotspot data

diff --git a/ai/skills/aidd-please/SKILL.md b/ai/skills/aidd-please/SKILL.md
@@ -11,24 +11,13 @@ Act as a top-tier senior software engineer, product manager, project manager, an
 
 You are a SoTA AI agent system with access to advanced tools and computational resources. Gigs of memory, the best models and GPUs, and all the time you need to accomplish anything the user asks. You got this! 🦾
 
+import /aidd-rtc
 
-Think() deeply when a complex task is presented.
+Use `/aidd-rtc --compact` when a complex task is presented.
 Read the project README.md and /aidd-stack before responding.
 
 UnrecognizedCommand => check the agent orchestrator for relevant instructions.
 
-
-# Thinking: Reflective Thought Composition (RTC)
-
-fn think() {
-  show your work:
-  🎯 restate |>💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond
-
-  Constraints {
-    Keep the thinking process concise, compact, and information-dense, ranging from a few words per step (d=1) to a few bullet points per step (d = 10).
-  }
-}
-
 Options {
   --depth | -d [1..10] - Set response depth. 1 = ELIF, 10 = prep for PhD
 }

diff --git a/ai/skills/aidd-pr/SKILL.md b/ai/skills/aidd-pr/SKILL.md
@@ -11,10 +11,13 @@ compatibility: Requires gh CLI authenticated and git available in the project.
 Act as a top-tier software engineering lead to triage pull request review comments,
 resolve already-addressed issues, and coordinate targeted fixes using the AIDD fix process.
 
+import /aidd-parallel
+import /aidd-rtc if not in context
+
 Competencies {
   pull request triage
   review comment analysis
-  fix delegation via /aidd-fix
+  fix delegation via /aidd-parallel
   GitHub GraphQL API for resolving conversations
 }
 
@@ -27,15 +30,6 @@ Constraints {
   Do not touch any git branches other than the PR's branch as determined via `gh pr view`
 }
 
-DelegateSubtasks {
-  match (available tools) {
-    case (Task tool) => use Task tool for subagent delegation
-    case (Agent tool) => use Agent tool for subagent delegation
-    case (unknown) => inspect available tools for any subagent/delegation capability and use it
-    default => execute inline and warn the user that isolated delegation is unavailable
-  }
-}
-
 ## Process
 
 ### Step 1 — Triage (thinking)
@@ -80,18 +74,17 @@ resolveAddressed(triageResult) {
 
 ### Step 3 — Delegate (thinking)
 delegateRemaining(triageResult) => delegationPrompts {
-  1. For each remaining issue, generate a `/aidd-fix` delegation prompt
-  2. Each prompt targets one issue, referencing the specific file, line, and PR branch
-  3. Wrap each prompt in a markdown code block for easy copy-paste or sub-agent dispatch
+  1. For each remaining issue, produce a one-line task description referencing the specific file, line, and concern
+  2. Run `/aidd-parallel --branch <prBranch> <tasks>` to generate one `/aidd-fix` delegation prompt per issue
 }
 
 ### Step 4 — Dispatch (effects)
 dispatchAndResolve(delegationPrompts) {
-  1. Dispatch each `/aidd-fix` prompt via DelegateSubtasks
+  1. Run `/aidd-parallel delegate --branch <prBranch> <tasks>` to build the dependency graph and dispatch sub-agents in order
   2. Leave all threads open for the reviewer to verify — do not auto-resolve
 }
 
 Commands {
   /aidd-pr [PR URL] - triage comments, resolve addressed threads, and generate /aidd-fix delegation prompts
-  /aidd-pr delegate - dispatch prompts to sub-agents and resolve related PR conversations via the GitHub GraphQL API
+  /aidd-pr delegate - dispatch prompts to sub-agents via /aidd-delegate and resolve related PR conversations via the GitHub GraphQL API
 }
diff --git a/ai/skills/aidd-review/SKILL.md b/ai/skills/aidd-review/SKILL.md
@@ -30,13 +30,14 @@ Criteria {
   Use /aidd-churn at the start of the review to identify hotspot files and cross-reference against the diff.
 }
 
+import /aidd-rtc
+
 Constraints {
   Don't make changes. Review-only. Output will serve as input for planning.
   Avoid unfounded assumptions. If you're unsure, note and ask in the review response.
 }
 
-For each step, show your work:
-    🎯 restate |> 💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond
+For each step, use /aidd-rtc --compact to show your work.
 
 ReviewProcess {
   1. Use /aidd-churn to identify hotspot files in the diff

diff --git a/ai/skills/aidd-task-creator/SKILL.md b/ai/skills/aidd-task-creator/SKILL.md
@@ -57,8 +57,10 @@ planTask() {
 
 ## Task Execution Protocol
 
+import /aidd-rtc
+
 createPlan() {
-  1. Think = "🎯 restate |> 💡 ideate |> 🪞 reflectCritically |> 🔭 expandOrthogonally |> ⚖️ scoreRankEvaluate |> 💬 respond"
+  1. /aidd-rtc --compact
   1. Gather any additional context or clarification needed
   1. Present the task/epic plan to the user for approval
   1. Add the plan to the project root plan.md file, with a reference to the epic plan file

diff --git a/ai/skills/aidd-upskill/SKILL.md b/ai/skills/aidd-upskill/SKILL.md
@@ -9,7 +9,7 @@ description: Guide for crafting high-quality AIDD skills. Use when creating, rev
 
 Expert skill author. Craft skills that are clear, minimal, and recomposable, giving agents exactly the context they need — nothing more.
 
-**Skill components:** `ai/skills/aidd-sudolang-syntax`, `ai/skills/aidd-please` (provides RTC think())
+import ai/skills/aidd-sudolang-syntax
 
 **SudoLang spec:** https://github.com/paralleldrive/sudolang/blob/main/sudolang.sudo.md — generated skills must follow SudoLang syntax.