From afc68c647141b34acd01972ba025ec5e0bb8abbf Mon Sep 17 00:00:00 2001 From: John Sell Date: Tue, 6 Oct 2026 21:08:35 -0400 Subject: [PATCH 01/10] docs(skills): create triage skill --- skills/build/triage/SKILL.md | 65 ++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 skills/build/triage/SKILL.md diff --git a/skills/build/triage/SKILL.md b/skills/build/triage/SKILL.md new file mode 100644 index 000000000..32d307314 --- /dev/null +++ b/skills/build/triage/SKILL.md @@ -0,0 +1,65 @@ +--- +name: triage +description: > + GitHub Issue Triage Workflow. +--- + +# Workflow + +GitHub issue triage workflow that classifies issues as: +- `agent/deferred` +- `agent/workable` +- `agent/duplicate` + +## Input + +```text +$GITHUB_REPO_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_REPO_URL -- execute triage against the provided GitHub repository. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issues + +Using the GitHub API, fetch the issues in `$GITHUB_REPO_URL` that have the +label `agent/allowed`. You MUST NOT read any issue that does not have the `agent/allowed` label. + +Output: `$LIST_OF_ISSUES` + +### Step 2: Classify Issues + +According to the criteria listed below, determine the classification each issue in `$LIST_OF_ISSUES`. +It MUST be one of the following: + +- `agent/duplicate` +Definition: This issue is duplicated by an issue in `$LIST_OF_ISSUES` and contains equal or lesser clarity of intent. This issue will be closed. + +- `agent/deferred` +Definition: This issue requires additional human input due to ambiguous intent, +conflicting intent [with other issues], or the issue appears to be misaligned with the overall project direction. + +- `agent/workable` +Definition: This issue contains clear intent, does not conflict with other issues, and is aligned with the overall project direction. + + +Output: `$ISSUE_TO_CLASSIFICATION_MAP` + +### Step 3: Map Actions to Classification + +For each issue in `$ISSUE_TO_CLASSIFICATION_MAP`, execute actions according to the label: + +_Note: If the label does not exist, create it._ + +- `agent/duplicate` +Action: Label the issue as `agent/duplicate`. Then, close the label. + +- `agent/deferred` +Action: Label the issue as `agent/deferred`. + +- `agent/workable` +Action: Label the issue as `agent/workable`. + From 5042af99c52526b40ac1e9bbf30de6a8dfd8a1f5 Mon Sep 17 00:00:00 2001 From: John Sell Date: Tue, 6 Oct 2026 21:25:09 -0400 Subject: [PATCH 02/10] docs(skills): create spec-implementation skill --- skills/build/spec-implementation/SKILL.md | 53 +++++++++++++++++++++++ skills/plan/spec/SKILL.md | 6 +++ 2 files changed, 59 insertions(+) create mode 100644 skills/build/spec-implementation/SKILL.md diff --git a/skills/build/spec-implementation/SKILL.md b/skills/build/spec-implementation/SKILL.md new file mode 100644 index 000000000..8aab76e77 --- /dev/null +++ b/skills/build/spec-implementation/SKILL.md @@ -0,0 +1,53 @@ +--- +name: spec-implementation +description: > + GitHub Issue to Specification Workflow +--- + +# Workflow + +GitHub issue to specification workflow. + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue + +Using the GitHub API, fetch the issue title & body of `$GITHUB_ISSUE_URL`. +Identify whether there is an existing pull request associated with this issue, +and whether a Jira issue is mentioned in the issue body or title (eg. HYPERSHELL-000). + +Output: (`$ISSUE_CONTENT`, `$ISSUE_NUMBER`, `$EXISTING_PR`[NULL or string], `$JIRA_ISSUE`[NULL or string]) + +### Step 2: Write and/or Update Specifications + +Read the [spec skill](skills/plan/spec/SKILL.md). + +In a new work tree (in a new directory), follow its workflow to codify the intent of `$ISSUE_CONTENT` in specifications. + +### Step 3: Commit and Push + +Commit the specification changes. + +IF `$EXISTING_PR` IS NOT NULL: +- Push to existing PR's branch +- Update PR body to match actual diff, if necessary. + +ELSE: +- Create a new branch for the issue of form `agent/work/issue/($JIRA_ISSUE ?? $ISSUE_NUMBER)` +- Push to branch +- Open Pull Request, link it to the issue +- PR Body must conform to SIMPLIFIED TECHNICAL ENGLISH STANDARD. + +### Step 4: Update Issue State + +Place label `agent/reviewable-spec` on `$GITHUB_ISSUE_URL`. diff --git a/skills/plan/spec/SKILL.md b/skills/plan/spec/SKILL.md index ae807a724..80c53e0ed 100644 --- a/skills/plan/spec/SKILL.md +++ b/skills/plan/spec/SKILL.md @@ -12,6 +12,12 @@ description: > Help the user create or change a spec that describes desired system behavior. +Note: Specifications are not purely additive. They codify _repository intent_ and +therefore must necessarily be utterly coherent and consistent always. More concretely, +most spec additions are accompanied by deletions & modifications in other specs. To that end, be +extremely thorough to understand the entire specification landscape when executing this +workflow. + ## User Input ```text From a0f248df796113d2712300a33e4f0877d99f4779 Mon Sep 17 00:00:00 2001 From: John Sell Date: Tue, 6 Oct 2026 21:38:58 -0400 Subject: [PATCH 03/10] docs(skills): create spec-review skill --- skills/build/spec-review/SKILL.md | 49 +++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 skills/build/spec-review/SKILL.md diff --git a/skills/build/spec-review/SKILL.md b/skills/build/spec-review/SKILL.md new file mode 100644 index 000000000..b181db861 --- /dev/null +++ b/skills/build/spec-review/SKILL.md @@ -0,0 +1,49 @@ +--- +name: spec-review +description: > + Specification Review Workflow +--- + +# Workflow + +Specification Review Workflow that assess a spec to be considered one of: + +- `agent/review-spec-rejected` +- `agent/review-spec-approved` + +## Input + +```text +$GITHUB_PR_URL $GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_PR_URL -- execute against the provided GitHub pull request. +- GITHUB_ISSUE_URL -- the GitHub issue the PR is addressing. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Pull Request + +Clone the repo at the state of `$GITHUB_PR_URL` and familiarize yourself +with the specification changes made in the PR. + +### Step 2: Review the Specification Changes + +Read the [spec skill](skills/plan/spec/SKILL.md). + +Assess the specifications according to: +- the rules in the skill +- faithfulness to the intent found in `$GITHUB_ISSUE_URL` +- consistency with established design, architecture, and general project direction patterns. + +Output: `$REVIEW_VERDICT` - One of +- `agent/review-spec-rejected` +- `agent/review-spec-approved` + +### Step 3: Update Issue State + +_Note: Create `$REVIEW_VERDICT` label if not exist._ + +Place label `$REVIEW_VERDICT` on `$GITHUB_ISSUE_URL` and `$GITHUB_PR_URL` From 59f7e0a048571f2b19b47b91d3e4de8ee7c977fa Mon Sep 17 00:00:00 2001 From: John Sell Date: Tue, 6 Oct 2026 21:41:17 -0400 Subject: [PATCH 04/10] docs(skills): create spec-review skill --- skills/build/spec-review/SKILL.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/skills/build/spec-review/SKILL.md b/skills/build/spec-review/SKILL.md index b181db861..006dd184e 100644 --- a/skills/build/spec-review/SKILL.md +++ b/skills/build/spec-review/SKILL.md @@ -47,3 +47,6 @@ Output: `$REVIEW_VERDICT` - One of _Note: Create `$REVIEW_VERDICT` label if not exist._ Place label `$REVIEW_VERDICT` on `$GITHUB_ISSUE_URL` and `$GITHUB_PR_URL` + +IF `$REVIEW_VERDICT` == `agent/review-spec-rejected`: +- Write rejection rationale as a comment on the PR. Use simplified technical english, and inline code review comments if applicable. From 331aec92bcd918c1ce9dfaa7813e6a2e08a49430 Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 09:12:59 -0400 Subject: [PATCH 05/10] typo --- skills/build/triage/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/build/triage/SKILL.md b/skills/build/triage/SKILL.md index 32d307314..89d264e74 100644 --- a/skills/build/triage/SKILL.md +++ b/skills/build/triage/SKILL.md @@ -55,7 +55,7 @@ For each issue in `$ISSUE_TO_CLASSIFICATION_MAP`, execute actions according to t _Note: If the label does not exist, create it._ - `agent/duplicate` -Action: Label the issue as `agent/duplicate`. Then, close the label. +Action: Label the issue as `agent/duplicate`. Then, close the issue. - `agent/deferred` Action: Label the issue as `agent/deferred`. From 1440dcb7fbc86a08daccc3060c1b54005e9b578b Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 10:13:24 -0400 Subject: [PATCH 06/10] replace agent/deferred with agent/needs-input --- skills/build/triage/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/build/triage/SKILL.md b/skills/build/triage/SKILL.md index 89d264e74..24ebf4146 100644 --- a/skills/build/triage/SKILL.md +++ b/skills/build/triage/SKILL.md @@ -7,7 +7,7 @@ description: > # Workflow GitHub issue triage workflow that classifies issues as: -- `agent/deferred` +- `agent/needs-input` - `agent/workable` - `agent/duplicate` @@ -38,7 +38,7 @@ It MUST be one of the following: - `agent/duplicate` Definition: This issue is duplicated by an issue in `$LIST_OF_ISSUES` and contains equal or lesser clarity of intent. This issue will be closed. -- `agent/deferred` +- `agent/needs-input` Definition: This issue requires additional human input due to ambiguous intent, conflicting intent [with other issues], or the issue appears to be misaligned with the overall project direction. @@ -57,8 +57,8 @@ _Note: If the label does not exist, create it._ - `agent/duplicate` Action: Label the issue as `agent/duplicate`. Then, close the issue. -- `agent/deferred` -Action: Label the issue as `agent/deferred`. +- `agent/needs-input` +Action: Label the issue as `agent/needs-input`. - `agent/workable` Action: Label the issue as `agent/workable`. From 8db487ffc34b252127b3d764b0c4af870987b52e Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 10:31:25 -0400 Subject: [PATCH 07/10] write code-implementation skill --- skills/build/code-implementation/SKILL.md | 68 +++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 skills/build/code-implementation/SKILL.md diff --git a/skills/build/code-implementation/SKILL.md b/skills/build/code-implementation/SKILL.md new file mode 100644 index 000000000..ef21cd33e --- /dev/null +++ b/skills/build/code-implementation/SKILL.md @@ -0,0 +1,68 @@ +--- +name: code-implementation +description: > + Code Implementation Workflow +--- + +# Workflow + +The code implementation workflow is responsible for reconciling a set of spec changes +to code, ensuring CI passes, and resolving any merge conflicts or rebase needs on an open PR. + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue and Open PR + +Fetch `$GITHUB_ISSUE_URL` and fully read its title and body. + +Discover the linked pull request. + +If no linked pull request: +- apply label `agent/blocked` to `$GITHUB_ISSUE_URL` (_Note: If the label does not exist, create it._) +- write a comment on the issue noting the reason. +- STOP. Do not execute any further steps. + +Output: `$LINKED_PULL_REQUEST` + +### Step 2: Identify State of Implementation + +Read contents of `$LINKED_PULL_REQUEST`, `$GITHUB_ISSUE_URL`, CI checks on `$LINKED_PULL_REQUEST`, and +mergeability of `$LINKED_PULL_REQUEST`. + + +### Step 3: Identify Spec Changes + +Clone the branch associated with `$LINKED_PULL_REQUEST`. Using the git history, identify the specification +changes introduced in `$LINKED_PULL_REQUEST`. Note that specification changes may not be purely additive, and +may touch many parts of the application. Removal of, and changes to, specifications are just as important +as new specifications. + + +### Step 4: Reconcile Specifications + +Execute the skills/build/reconcile skill against the specification changes identified in Step 2. + + +### Step 5: Review Changes + +Execute the skills/review/amber-review skill against the implementation produced by Step 3. + +If the review produces findings: +- Return to Step 4 and address the findings +Else: +- Address any failing CI checks found in Step 2. +- Address any merge conflicts found in Step 2. +- Commit (if not already) and push code to `$LINKED_PULL_REQUEST`. +- Write label `agent/reviewable-code` to `$GITHUB_ISSUE_URL` + +_Note: If the label does not exist, create it._ From 2fd1b9e1b5c5aac4ba4fb719654b378e2a20db3e Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 10:36:58 -0400 Subject: [PATCH 08/10] move agent loop skills to agent-loop/ --- skills/{build => agent-loop}/code-implementation/SKILL.md | 0 skills/{build => agent-loop}/spec-implementation/SKILL.md | 0 skills/{build => agent-loop}/spec-review/SKILL.md | 0 skills/{build => agent-loop}/triage/SKILL.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename skills/{build => agent-loop}/code-implementation/SKILL.md (100%) rename skills/{build => agent-loop}/spec-implementation/SKILL.md (100%) rename skills/{build => agent-loop}/spec-review/SKILL.md (100%) rename skills/{build => agent-loop}/triage/SKILL.md (100%) diff --git a/skills/build/code-implementation/SKILL.md b/skills/agent-loop/code-implementation/SKILL.md similarity index 100% rename from skills/build/code-implementation/SKILL.md rename to skills/agent-loop/code-implementation/SKILL.md diff --git a/skills/build/spec-implementation/SKILL.md b/skills/agent-loop/spec-implementation/SKILL.md similarity index 100% rename from skills/build/spec-implementation/SKILL.md rename to skills/agent-loop/spec-implementation/SKILL.md diff --git a/skills/build/spec-review/SKILL.md b/skills/agent-loop/spec-review/SKILL.md similarity index 100% rename from skills/build/spec-review/SKILL.md rename to skills/agent-loop/spec-review/SKILL.md diff --git a/skills/build/triage/SKILL.md b/skills/agent-loop/triage/SKILL.md similarity index 100% rename from skills/build/triage/SKILL.md rename to skills/agent-loop/triage/SKILL.md From c72f1525f4c931a1064bc58146d4545fca5747a2 Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 10:46:29 -0400 Subject: [PATCH 09/10] add code-review skill --- skills/agent-loop/code-review/SKILL.md | 66 ++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 skills/agent-loop/code-review/SKILL.md diff --git a/skills/agent-loop/code-review/SKILL.md b/skills/agent-loop/code-review/SKILL.md new file mode 100644 index 000000000..b578dad3b --- /dev/null +++ b/skills/agent-loop/code-review/SKILL.md @@ -0,0 +1,66 @@ +--- +name: code-review +description: > + Code Review Workflow +--- + +# Workflow + +Code review workflow that classifies issues as: +- `agent/review-code-rejected` +- `agent/review-code-approved` + +Review is rejected for any of the following reasons: +- Implementation review has findings +- Failing CI +- Merge conflicts +- Needs rebase + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue and Linked PR + +Using the GitHub API, fetch `$GITHUB_ISSUE_URL`. + +Read the issue title and body and identify the linked PR. + +Output: (`$LINKED_PR`, `$ISSUE_CONTENTS`) + +### Step 2: Review the Implementation + +Execute skills/review/amber-review against `$LINKED_PR`. Review in the +context of `$ISSUE_CONTENTS`. + +Review must be rejected for any of the following reasons: +- Implementation review has findings +- Failing CI +- Merge conflicts +- Needs rebase + +Verdict must be one of: +- `agent/review-code-rejected` +- `agent/review-code-approved` + +Output: (`$VERDICT`, `$REJECTION_RATIONALE` (NULL or string)) + + +### Step 3: Communicate Outcome + +_Note: If a label does not exist, create it._ + +Apply `$VERDICT` label to `$GITHUB_ISSUE_URL`. + +IF `$VERDICT` == `agent/review-code-rejected`: +- Add a comment to `$GITHUB_ISSUE_URL` communicating `$REJECTION_RATIONALE` that + adheres to the simplified technical english standard. + From 9482e0d7c16c9248bbaf06f7c865555ef520c628 Mon Sep 17 00:00:00 2001 From: John Sell Date: Wed, 7 Oct 2026 10:57:10 -0400 Subject: [PATCH 10/10] docs(skills): address Amber review on agent-loop skills Fix broken relative links to the spec skill, link the Simplified Technical English references to ASD-STE100, and strip trailing whitespace. Co-Authored-By: Claude Opus 4.8 --- skills/agent-loop/code-implementation/SKILL.md | 4 ++-- skills/agent-loop/spec-implementation/SKILL.md | 6 +++--- skills/agent-loop/spec-review/SKILL.md | 8 ++++---- skills/agent-loop/triage/SKILL.md | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/skills/agent-loop/code-implementation/SKILL.md b/skills/agent-loop/code-implementation/SKILL.md index ef21cd33e..5560ed90e 100644 --- a/skills/agent-loop/code-implementation/SKILL.md +++ b/skills/agent-loop/code-implementation/SKILL.md @@ -25,7 +25,7 @@ Supported arguments: Fetch `$GITHUB_ISSUE_URL` and fully read its title and body. -Discover the linked pull request. +Discover the linked pull request. If no linked pull request: - apply label `agent/blocked` to `$GITHUB_ISSUE_URL` (_Note: If the label does not exist, create it._) @@ -55,7 +55,7 @@ Execute the skills/build/reconcile skill against the specification changes ident ### Step 5: Review Changes -Execute the skills/review/amber-review skill against the implementation produced by Step 3. +Execute the skills/review/amber-review skill against the implementation produced by Step 3. If the review produces findings: - Return to Step 4 and address the findings diff --git a/skills/agent-loop/spec-implementation/SKILL.md b/skills/agent-loop/spec-implementation/SKILL.md index 8aab76e77..5bc83310d 100644 --- a/skills/agent-loop/spec-implementation/SKILL.md +++ b/skills/agent-loop/spec-implementation/SKILL.md @@ -23,14 +23,14 @@ Supported arguments: ### Step 1: Read Issue Using the GitHub API, fetch the issue title & body of `$GITHUB_ISSUE_URL`. -Identify whether there is an existing pull request associated with this issue, +Identify whether there is an existing pull request associated with this issue, and whether a Jira issue is mentioned in the issue body or title (eg. HYPERSHELL-000). Output: (`$ISSUE_CONTENT`, `$ISSUE_NUMBER`, `$EXISTING_PR`[NULL or string], `$JIRA_ISSUE`[NULL or string]) ### Step 2: Write and/or Update Specifications -Read the [spec skill](skills/plan/spec/SKILL.md). +Read the [spec skill](../../plan/spec/SKILL.md). In a new work tree (in a new directory), follow its workflow to codify the intent of `$ISSUE_CONTENT` in specifications. @@ -46,7 +46,7 @@ ELSE: - Create a new branch for the issue of form `agent/work/issue/($JIRA_ISSUE ?? $ISSUE_NUMBER)` - Push to branch - Open Pull Request, link it to the issue -- PR Body must conform to SIMPLIFIED TECHNICAL ENGLISH STANDARD. +- PR Body must conform to [SIMPLIFIED TECHNICAL ENGLISH STANDARD](https://en.wikipedia.org/wiki/Simplified_Technical_English). ### Step 4: Update Issue State diff --git a/skills/agent-loop/spec-review/SKILL.md b/skills/agent-loop/spec-review/SKILL.md index 006dd184e..4d3a7af16 100644 --- a/skills/agent-loop/spec-review/SKILL.md +++ b/skills/agent-loop/spec-review/SKILL.md @@ -6,7 +6,7 @@ description: > # Workflow -Specification Review Workflow that assess a spec to be considered one of: +Specification Review Workflow that assess a spec to be considered one of: - `agent/review-spec-rejected` - `agent/review-spec-approved` @@ -31,14 +31,14 @@ with the specification changes made in the PR. ### Step 2: Review the Specification Changes -Read the [spec skill](skills/plan/spec/SKILL.md). +Read the [spec skill](../../plan/spec/SKILL.md). Assess the specifications according to: - the rules in the skill - faithfulness to the intent found in `$GITHUB_ISSUE_URL` - consistency with established design, architecture, and general project direction patterns. -Output: `$REVIEW_VERDICT` - One of +Output: `$REVIEW_VERDICT` - One of - `agent/review-spec-rejected` - `agent/review-spec-approved` @@ -49,4 +49,4 @@ _Note: Create `$REVIEW_VERDICT` label if not exist._ Place label `$REVIEW_VERDICT` on `$GITHUB_ISSUE_URL` and `$GITHUB_PR_URL` IF `$REVIEW_VERDICT` == `agent/review-spec-rejected`: -- Write rejection rationale as a comment on the PR. Use simplified technical english, and inline code review comments if applicable. +- Write rejection rationale as a comment on the PR. Use [simplified technical english](https://en.wikipedia.org/wiki/Simplified_Technical_English), and inline code review comments if applicable. diff --git a/skills/agent-loop/triage/SKILL.md b/skills/agent-loop/triage/SKILL.md index 24ebf4146..3bbed0930 100644 --- a/skills/agent-loop/triage/SKILL.md +++ b/skills/agent-loop/triage/SKILL.md @@ -33,7 +33,7 @@ Output: `$LIST_OF_ISSUES` ### Step 2: Classify Issues According to the criteria listed below, determine the classification each issue in `$LIST_OF_ISSUES`. -It MUST be one of the following: +It MUST be one of the following: - `agent/duplicate` Definition: This issue is duplicated by an issue in `$LIST_OF_ISSUES` and contains equal or lesser clarity of intent. This issue will be closed.