diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..db83f7b --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "changehack-local-plugins", + "interface": { + "displayName": "changeHack Local Plugins" + }, + "plugins": [ + { + "name": "subagent-orchestration-kit", + "source": { + "source": "local", + "path": "./plugins/subagent-orchestration-kit" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/plugins/subagent-orchestration-kit/.codex-plugin/plugin.json b/plugins/subagent-orchestration-kit/.codex-plugin/plugin.json new file mode 100644 index 0000000..7709ef7 --- /dev/null +++ b/plugins/subagent-orchestration-kit/.codex-plugin/plugin.json @@ -0,0 +1,45 @@ +{ + "name": "subagent-orchestration-kit", + "version": "0.1.0", + "description": "Reusable role prompts and orchestration rules for idea generation, implementation, evaluation, and error checking.", + "author": { + "name": "Akira Kakiuchi", + "email": "support@example.com", + "url": "https://github.com/Asheze1127" + }, + "homepage": "https://github.com/Asheze1127/HackHub", + "repository": "https://github.com/Asheze1127/HackHub", + "license": "UNLICENSED", + "keywords": [ + "subagent", + "orchestration", + "evaluation", + "review", + "planning" + ], + "skills": "./skills/", + "interface": { + "displayName": "Subagent Orchestration Kit", + "shortDescription": "Reusable sub-agent playbooks for product work and implementation loops", + "longDescription": "Packages reusable role definitions, project-context handling, and an implementation loop for idea consulting, coding, evaluation, error checking, and orchestration across repos.", + "developerName": "Akira Kakiuchi", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Read", + "Write" + ], + "websiteURL": "https://github.com/Asheze1127/HackHub", + "privacyPolicyURL": "https://github.com/Asheze1127/HackHub", + "termsOfServiceURL": "https://github.com/Asheze1127/HackHub", + "defaultPrompt": [ + "Use the orchestrator cycle to plan and ship the next slice.", + "Use idea-consultant to propose feature options from project docs.", + "Use error-checker to compare implementation against specs." + ], + "brandColor": "#0F766E", + "composerIcon": "./assets/subagent-kit.svg", + "logo": "./assets/subagent-kit.svg", + "screenshots": [] + } +} diff --git a/plugins/subagent-orchestration-kit/README.md b/plugins/subagent-orchestration-kit/README.md new file mode 100644 index 0000000..e5d6b34 --- /dev/null +++ b/plugins/subagent-orchestration-kit/README.md @@ -0,0 +1,60 @@ +# Subagent Orchestration Kit + +This plugin packages a reusable improvement loop for product work and implementation work. + +It does **not** add new first-class agent types to Codex. Instead, it gives you a portable set of: + +- role definitions +- project-context files +- orchestration rules +- usage guidance you can reuse in other repositories + +## Included roles + +- `idea-consultant` + - proposes feature options and product slices from source docs +- `coding-worker` + - implements one bounded slice with clear file ownership +- `implementation-evaluator` + - verifies acceptance criteria and test coverage for the slice +- `error-checker` + - compares code against specs, product direction, and architectural constraints +- `reviewer` + - reviews the concrete diff for regressions, maintainability, and missed tests +- `orchestrator-cycle` + - coordinates the loop and keeps scope under control + +## Current repo context + +This copy includes a project context file for the current HackHub direction: + +- [contexts/hackhub-product-overview.md](./contexts/hackhub-product-overview.md) + +That context merges: + +- `changeHack` +- `progress-checker` +- `hack-evaluater` +- the user override that the product must support multiple hackathons and serve participants, sponsors, and organizers + +## How to use in this repo + +1. Start with `orchestrator-cycle`. + Use [contexts/hackhub-product-overview.md](./contexts/hackhub-product-overview.md) as the project overview file. +2. Use `idea-consultant` to decide the smallest valuable slice. +3. Give `coding-worker` exclusive ownership of the write scope. +4. Run `error-checker` against docs and code. +5. Run `implementation-evaluator` against the agreed acceptance criteria. +6. Repeat in small slices. + +## How to reuse in another repo + +1. Copy `plugins/subagent-orchestration-kit` into the target repo. +2. Copy or recreate `.agents/plugins/marketplace.json`, or merge the plugin entry into the target repo marketplace. +3. Replace `contexts/hackhub-product-overview.md` with a project-specific overview based on [contexts/project-overview-template.md](./contexts/project-overview-template.md). +4. Update the source-of-truth file list inside the skill docs if the target repo uses different spec paths. +5. Keep the same role split unless the target repo needs fewer roles. + +## Portability note + +If the plugin is not installed in a target environment, the files still work as prompt packs and operating docs. You can open the relevant `SKILL.md` files and use them directly when spawning helper agents. diff --git a/plugins/subagent-orchestration-kit/agents/openai.yaml b/plugins/subagent-orchestration-kit/agents/openai.yaml new file mode 100644 index 0000000..fca76d7 --- /dev/null +++ b/plugins/subagent-orchestration-kit/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Subagent Orchestration Kit" + short_description: "Reusable role prompts for idea consulting, coding, evaluation, and implementation review" + icon_small: "./assets/subagent-kit.svg" + icon_large: "./assets/subagent-kit.svg" + default_prompt: "Use the subagent orchestration kit to plan the next slice, implement it with a bounded worker, and verify it with evaluator and error-checker roles." diff --git a/plugins/subagent-orchestration-kit/assets/subagent-kit.svg b/plugins/subagent-orchestration-kit/assets/subagent-kit.svg new file mode 100644 index 0000000..c0b0cd7 --- /dev/null +++ b/plugins/subagent-orchestration-kit/assets/subagent-kit.svg @@ -0,0 +1,10 @@ + + Subagent Orchestration Kit + Three coordinated blocks around a central hub. + + + + + + + diff --git a/plugins/subagent-orchestration-kit/contexts/hackhub-product-overview.md b/plugins/subagent-orchestration-kit/contexts/hackhub-product-overview.md new file mode 100644 index 0000000..32d59bb --- /dev/null +++ b/plugins/subagent-orchestration-kit/contexts/hackhub-product-overview.md @@ -0,0 +1,85 @@ +# HackHub Product Overview + +## Source of truth order + +Use this order when the repository is inconsistent: + +1. Direct user instructions in the current thread +2. This file +3. The current repo product and architecture docs +4. Any sibling-repo specs that this product explicitly inherits from +5. Current implementation + +## Current workspace path mapping + +This context file is written for the current HackHub workspace layout. + +From the `changeHack/` repo root, the intended doc locations are: + +- `docs/` +- `../progress-checker/docs/` +- `../hack-evaluater/docs/` + +If those sibling paths do not exist in another repo, do not follow them. Replace this file with a repo-specific overview derived from [project-overview-template.md](./project-overview-template.md) first. + +## Product direction + +The intended product is not just the current `changeHack` MVP. + +It is a combined product that should merge: + +- the Slack-driven progress and question workflow from `progress-checker` +- the multi-hackathon and role-aware product model from `hack-evaluater` + +The product must support multiple hackathons and serve: + +- participants / hackers +- mentors / judges +- organizers +- corporate sponsors +- tenant or platform admins when needed + +## Problem the product solves + +- Participants need a low-friction way to ask questions and share progress. +- Mentors need structured, triaged questions instead of unformatted Slack messages. +- Organizers need a web view of progress, blockers, and unanswered questions across hackathons. +- Sponsors need scoped access to the hackathons and teams they are allowed to see. + +## Combined product shape + +### From progress-checker + +- `/progress` modal and progress board flow +- `/question` modal and AI first response flow +- async queue architecture for Slack's 3-second constraint +- web dashboard for progress and questions +- future Slack discussion to GitHub issue flow + +### From hack-evaluater + +- multi-hackathon structure +- role separation and scoped permissions +- web architecture patterns for feature/container based UI +- backend layering and clearer domain boundaries +- sponsor and organizer facing workflows + +## Known current drift + +The current `changeHack` implementation is still closer to a KCL-specific support hub MVP: + +- single-event assumptions remain in docs and code +- sponsor and organizer flows are not implemented +- multi-hackathon modeling is not implemented +- mentor-only operational views are incomplete +- Slack discussion to Issue flow is still missing + +Treat these as implementation gaps, not final product decisions. + +## Planning constraints + +- Preserve Slack-first entry points. +- Keep heavy work asynchronous. +- Do not break the existing `changeHack` MVP while expanding scope. +- Favor small vertical slices over broad rewrites. +- When docs conflict, note the conflict explicitly before choosing a path. diff --git a/plugins/subagent-orchestration-kit/contexts/project-overview-template.md b/plugins/subagent-orchestration-kit/contexts/project-overview-template.md new file mode 100644 index 0000000..9d8ac4a --- /dev/null +++ b/plugins/subagent-orchestration-kit/contexts/project-overview-template.md @@ -0,0 +1,40 @@ +# Project Overview Template + +## Source of truth order + +1. Current user instructions +2. This file +3. Primary product specs +4. Architecture and permission docs +5. Current implementation + +## Product direction + +- What the product is +- Which older repos or docs it merges +- Which user roles matter most +- Which scope assumptions are critical + +## Target users + +- user group 1 +- user group 2 +- user group 3 + +## Core workflows + +- workflow 1 +- workflow 2 +- workflow 3 + +## Non-negotiable constraints + +- architecture constraint +- security constraint +- product constraint +- delivery constraint + +## Known drift + +- docs vs implementation mismatch 1 +- docs vs implementation mismatch 2 diff --git a/plugins/subagent-orchestration-kit/skills/coding-worker/SKILL.md b/plugins/subagent-orchestration-kit/skills/coding-worker/SKILL.md new file mode 100644 index 0000000..d51a930 --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/coding-worker/SKILL.md @@ -0,0 +1,39 @@ +--- +name: coding-worker +description: Implement one bounded slice with clear ownership, tests, and minimal scope creep. +--- + +# Coding Worker + +## Overview + +Use this skill for implementation once the orchestrator has already chosen a slice. + +This role owns one bounded write scope and should avoid expanding the task. + +## Required inputs + +- exact acceptance criteria +- the files or modules this role owns +- known constraints from the project overview + - in this repo: `../../contexts/hackhub-product-overview.md` +- any test requirements for the slice + +## Required behavior + +- Implement only the assigned slice. +- Preserve existing behavior outside the slice. +- Add or update tests for the touched area. +- Surface blockers instead of silently changing scope. + +## Deliverables + +- code changes +- tests or verification updates +- short note on any unresolved risk + +## Guardrails + +- Do not redefine the product while implementing. +- Do not take ownership of files assigned to another worker. +- Prefer small diffs over broad refactors unless the slice explicitly requires one. diff --git a/plugins/subagent-orchestration-kit/skills/error-checker/SKILL.md b/plugins/subagent-orchestration-kit/skills/error-checker/SKILL.md new file mode 100644 index 0000000..74fbcaf --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/error-checker/SKILL.md @@ -0,0 +1,69 @@ +--- +name: error-checker +description: Compare the repository's code and plans against the actual product direction, specs, and architectural constraints. +--- + +# Error Checker + +## Overview + +Use this skill to find implementation drift. + +This role is not only a bug checker. It checks whether the repository is moving in the wrong direction. + +## Required inputs + +- the project overview file + - in this repo: `../../contexts/hackhub-product-overview.md` + - in another repo: the project-specific overview that replaced it +- relevant specs and architecture docs +- the code or plan under review + +## What to look for + +### Product drift + +- current implementation assumes a smaller product than the docs require +- single-event assumptions where multi-hackathon support is required +- mentor-only assumptions where sponsor or organizer workflows are required + +### Architectural drift + +- synchronous handling where async design is required +- permission shortcuts that violate the intended role model +- hard-coded assumptions that block future role or tenant expansion + +### Implementation gaps + +- documented flows with no code path +- partial flows with no persistence or no UI +- UI routes that exist without backend support +- backend support that exists without user-facing flow + +### Quality problems + +- missing tests in modified areas +- broken or stale docs after implementation +- hidden coupling and poor ownership boundaries + +## Output format + +List findings in severity order: + +1. `critical` +2. `high` +3. `medium` +4. `low` + +Each finding should include: + +- what is wrong +- why it matters +- where it shows up +- the narrowest fix that would reduce the problem + +## Guardrails + +- Do not treat every future feature as a bug. +- Focus on real mismatches between product direction, docs, and implementation. +- Flag contradictions explicitly when the source docs disagree. diff --git a/plugins/subagent-orchestration-kit/skills/idea-consultant/SKILL.md b/plugins/subagent-orchestration-kit/skills/idea-consultant/SKILL.md new file mode 100644 index 0000000..856df6a --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/idea-consultant/SKILL.md @@ -0,0 +1,49 @@ +--- +name: idea-consultant +description: Propose the next useful product or implementation slice without losing sight of the actual product direction. +--- + +# Idea Consultant + +## Overview + +Use this skill to decide **what to build next**. + +This role turns product docs, architecture docs, and implementation gaps into a concrete next slice. + +## Required inputs + +- the project overview file + - in this repo: `../../contexts/hackhub-product-overview.md` + - in another repo: the project-specific overview that replaced it +- the main product spec +- current gap analysis or known missing features +- any direct user overrides from the current thread + +## Required behavior + +- Start from the real product, not just the current codebase. +- Prefer the smallest slice that unlocks the next important workflow. +- Call out when docs and implementation disagree. +- Separate: + - product requirement + - implementation constraint + - optional enhancement + +## Good output + +Return a short decision memo with: + +1. `next slice` +2. `user value` +3. `why now` +4. `minimal implementation` +5. `acceptance criteria` +6. `follow-up slices` + +## Guardrails + +- Do not invent features that contradict the project overview. +- Do not prioritize polish over broken or missing core flows. +- When the product is multi-tenant or multi-hackathon, explicitly check whether the proposed slice preserves that direction. +- Treat role and permission mismatches as product problems, not just technical debt. diff --git a/plugins/subagent-orchestration-kit/skills/implementation-evaluator/SKILL.md b/plugins/subagent-orchestration-kit/skills/implementation-evaluator/SKILL.md new file mode 100644 index 0000000..791c2f4 --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/implementation-evaluator/SKILL.md @@ -0,0 +1,37 @@ +--- +name: implementation-evaluator +description: Verify that an implemented slice meets acceptance criteria, tests, and basic quality expectations. +--- + +# Implementation Evaluator + +## Overview + +Use this skill after implementation to decide whether the slice is actually done. + +This role does not redesign the feature. It checks whether the agreed slice now works. + +## Evaluation checklist + +- Does the implementation still match the active project overview? +- Does the change satisfy the written acceptance criteria? +- Are the tests appropriate for the changed behavior? +- Is the implementation smaller and more direct than alternatives? +- Did the change accidentally widen scope? +- Are there obvious regressions or missing edge cases? + +## Output format + +Return: + +1. `pass` or `fail` +2. acceptance criteria status +3. test status +4. remaining risks +5. exact follow-up if it fails + +## Guardrails + +- Keep the judgment tied to the agreed slice. +- Distinguish hard failures from future improvements. +- If the slice passes but the larger product is still incomplete, say that clearly. diff --git a/plugins/subagent-orchestration-kit/skills/orchestrator-cycle/SKILL.md b/plugins/subagent-orchestration-kit/skills/orchestrator-cycle/SKILL.md new file mode 100644 index 0000000..7147d10 --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/orchestrator-cycle/SKILL.md @@ -0,0 +1,66 @@ +--- +name: orchestrator-cycle +description: Coordinate a reusable sub-agent improvement loop across ideation, implementation, evaluation, and drift checking. +--- + +# Orchestrator Cycle + +## Overview + +Use this skill when a repository needs a repeatable improvement loop instead of a single isolated edit. + +This role is the coordinator. It does not own every edit itself. It owns: + +- choosing the next slice +- assigning clear write ownership +- keeping the loop small +- deciding when a slice is ready to merge + +## Required startup + +Before proposing work: + +1. Read the project overview under `../../contexts/`. + In this repo, that file is `../../contexts/hackhub-product-overview.md`. + In another repo, use the project-specific overview that replaced it. +2. Read the product and architecture docs that the overview points to. +3. Identify the smallest vertical slice that reduces the most important gap. +4. Write down acceptance criteria before implementation starts. + +## Recommended role split + +- `idea-consultant` + - decides what should be built next and why +- `coding-worker` + - implements one bounded slice +- `error-checker` + - finds drift against docs, product direction, and architecture +- `implementation-evaluator` + - verifies the slice against acceptance criteria and tests +- `reviewer` + - reviews the concrete diff for regressions and maintainability + +## Coordination rules + +- Give each write task a single owner. +- Run read-only exploration in parallel whenever possible. +- Do not let `idea-consultant` implement code. +- Do not let `coding-worker` redefine product direction while coding. +- Run `error-checker` after each meaningful implementation step. +- Run `implementation-evaluator` before merge or PR creation. +- Run `reviewer` on the final diff before merge or PR creation. + +## Output format + +For each loop, produce: + +1. the chosen slice +2. why it is the next slice +3. acceptance criteria +4. write owner +5. verification owner +6. remaining risks + +## Reuse guidance + +When reused in another repo, replace the project overview file first. The orchestration rules can stay mostly unchanged. diff --git a/plugins/subagent-orchestration-kit/skills/reviewer/SKILL.md b/plugins/subagent-orchestration-kit/skills/reviewer/SKILL.md new file mode 100644 index 0000000..4d9d1b5 --- /dev/null +++ b/plugins/subagent-orchestration-kit/skills/reviewer/SKILL.md @@ -0,0 +1,41 @@ +--- +name: reviewer +description: Review a concrete change for regressions, maintainability issues, and missing tests after the slice is implemented. +--- + +# Reviewer + +## Overview + +Use this skill after a concrete diff exists. + +This role focuses on the implemented change itself, not broad product ideation. + +## What to review + +- consistency with the active project overview +- behavioral regressions +- missing edge cases +- poor naming or unclear control flow +- hidden coupling +- missing or weak tests +- security or validation gaps in the touched area + +## Output format + +Return findings first, ordered by severity. + +Each finding should include: + +- path +- why it is a problem +- the user-visible or maintenance impact +- the narrowest practical fix + +If there are no findings, say so explicitly and mention residual risks or test gaps. + +## Guardrails + +- Do not restate the whole implementation unless needed. +- Prefer concrete findings over generic advice. +- Keep focus on the actual diff, not the entire repo.