From 559c97219df279a4ce68ad763b5280bcf7682862 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 27 Jul 2026 13:25:30 -0400 Subject: [PATCH 01/32] Add immutable skill provenance --- LICENSES/Anthropic-security-review-MIT.txt | 21 +++ LICENSES/Apache-2.0.txt | 201 +++++++++++++++++++++ LICENSES/Superpowers-MIT.txt | 21 +++ THIRD_PARTY_NOTICES.md | 57 ++++++ UPSTREAMS.json | 163 +++++++++++++++++ commands/agents-md-improver.md | 1 + commands/agents-md-revise.md | 1 + commands/code-architect.md | 1 + commands/code-explorer.md | 1 + commands/code-review.md | 1 + commands/code-reviewer.md | 1 + commands/feature-dev.md | 1 + commands/frontend-design.md | 1 + commands/mcp-builder.md | 3 +- commands/security-review.md | 1 + commands/skill-creator.md | 3 +- package.json | 7 +- skills/agents-md-improver/SKILL.md | 2 +- skills/agents-md-revise/SKILL.md | 2 +- skills/code-architect/SKILL.md | 2 +- skills/code-explorer/SKILL.md | 2 +- skills/code-review/SKILL.md | 2 +- skills/code-reviewer/SKILL.md | 2 +- skills/feature-dev/SKILL.md | 2 +- skills/frontend-design/SKILL.md | 2 +- skills/mcp-builder/SKILL.md | 4 +- skills/security-review/SKILL.md | 2 +- skills/skill-creator/SKILL.md | 4 +- tests/provenance.test.mjs | 73 ++++++++ 29 files changed, 567 insertions(+), 17 deletions(-) create mode 100644 LICENSES/Anthropic-security-review-MIT.txt create mode 100644 LICENSES/Apache-2.0.txt create mode 100644 LICENSES/Superpowers-MIT.txt create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 UPSTREAMS.json create mode 100644 tests/provenance.test.mjs diff --git a/LICENSES/Anthropic-security-review-MIT.txt b/LICENSES/Anthropic-security-review-MIT.txt new file mode 100644 index 0000000..a8e23ec --- /dev/null +++ b/LICENSES/Anthropic-security-review-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Anthropic + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSES/Apache-2.0.txt b/LICENSES/Apache-2.0.txt new file mode 100644 index 0000000..0fe7cfb --- /dev/null +++ b/LICENSES/Apache-2.0.txt @@ -0,0 +1,201 @@ +Apache License +Version 2.0, January 2004 +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, +and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by +the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all +other entities that control, are controlled by, or are under common +control with that entity. For the purposes of this definition, +"control" means (i) the power, direct or indirect, to cause the +direction or management of such entity, whether by contract or +otherwise, or (ii) ownership of fifty percent (50%) or more of the +outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity +exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, +including but not limited to software source code, documentation +source, and configuration files. + +"Object" form shall mean any form resulting from mechanical +transformation or translation of a Source form, including but +not limited to compiled object code, generated documentation, +and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or +Object form, made available under the License, as indicated by a +copyright notice that is included in or attached to the work +(an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object +form, that is based on (or derived from) the Work and for which the +editorial revisions, annotations, elaborations, or other modifications +represent, as a whole, an original work of authorship. For the purposes +of this License, Derivative Works shall not include works that remain +separable from, or merely link (or bind by name) to the interfaces of, +the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including +the original version of the Work and any modifications or additions +to that Work or Derivative Works thereof, that is intentionally +submitted to Licensor for inclusion in the Work by the copyright owner +or by an individual or Legal Entity authorized to submit on behalf of +the copyright owner. For the purposes of this definition, "submitted" +means any form of electronic, verbal, or written communication sent +to the Licensor or its representatives, including but not limited to +communication on electronic mailing lists, source code control systems, +and issue tracking systems that are managed by, or on behalf of, the +Licensor for the purpose of discussing and improving the Work, but +excluding communication that is conspicuously marked or otherwise +designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity +on behalf of whom a Contribution has been received by Licensor and +subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of +this License, each Contributor hereby grants to You a perpetual, +worldwide, non-exclusive, no-charge, royalty-free, irrevocable +copyright license to reproduce, prepare Derivative Works of, +publicly display, publicly perform, sublicense, and distribute the +Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of +this License, each Contributor hereby grants to You a perpetual, +worldwide, non-exclusive, no-charge, royalty-free, irrevocable +(except as stated in this section) patent license to make, have made, +use, offer to sell, sell, import, and otherwise transfer the Work, +where such license applies only to those patent claims licensable +by such Contributor that are necessarily infringed by their +Contribution(s) alone or by combination of their Contribution(s) +with the Work to which such Contribution(s) was submitted. If You +institute patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Work +or a Contribution incorporated within the Work constitutes direct +or contributory patent infringement, then any patent licenses +granted to You under this License for that Work shall terminate +as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the +Work or Derivative Works thereof in any medium, with or without +modifications, and in Source or Object form, provided that You +meet the following conditions: + +(a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + +(b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + +(c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + +(d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + +You may add Your own copyright statement to Your modifications and +may provide additional or different license terms and conditions +for use, reproduction, or distribution of Your modifications, or +for any such Derivative Works as a whole, provided Your use, +reproduction, and distribution of the Work otherwise complies with +the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, +any Contribution intentionally submitted for inclusion in the Work +by You to the Licensor shall be under the terms and conditions of +this License, without any additional terms or conditions. +Notwithstanding the above, nothing herein shall supersede or modify +the terms of any separate license agreement you may have executed +with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade +names, trademarks, service marks, or product names of the Licensor, +except as required for reasonable and customary use in describing the +origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or +agreed to in writing, Licensor provides the Work (and each +Contributor provides its Contributions) on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +implied, including, without limitation, any warranties or conditions +of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A +PARTICULAR PURPOSE. You are solely responsible for determining the +appropriateness of using or redistributing the Work and assume any +risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, +whether in tort (including negligence), contract, or otherwise, +unless required by applicable law (such as deliberate and grossly +negligent acts) or agreed to in writing, shall any Contributor be +liable to You for damages, including any direct, indirect, special, +incidental, or consequential damages of any character arising as a +result of this License or out of the use or inability to use the +Work (including but not limited to damages for loss of goodwill, +work stoppage, computer failure or malfunction, or any and all +other commercial damages or losses), even if such Contributor +has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing +the Work or Derivative Works thereof, You may choose to offer, +and charge a fee for, acceptance of support, warranty, indemnity, +or other liability obligations and/or rights consistent with this +License. However, in accepting such obligations, You may act only +on Your own behalf and on Your sole responsibility, not on behalf +of any other Contributor, and only if You agree to indemnify, +defend, and hold each Contributor harmless for any liability +incurred by, or claims asserted against, such Contributor by reason +of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + +To apply the Apache License to your work, attach the following +boilerplate notice, with the fields enclosed by brackets "[]" +replaced with your own identifying information. (Don't include +the brackets!) The text should be enclosed in the appropriate +comment syntax for the file format. We also recommend that a +file or class name and description of purpose be included on the +same "printed page" as the copyright notice for easier +identification within third-party archives. + +Copyright 2026 Anthropic, PBC. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/LICENSES/Superpowers-MIT.txt b/LICENSES/Superpowers-MIT.txt new file mode 100644 index 0000000..abf0390 --- /dev/null +++ b/LICENSES/Superpowers-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Jesse Vincent + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..c10b4b9 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,57 @@ +# Third-Party Notices + +The repository wrapper, plugin integration, packaging, tests, and original +documentation are licensed under the root MIT `LICENSE` unless a file states +otherwise. + +The skills and generated command prompts are modified derivatives of the +sources recorded in `UPSTREAMS.json`. They are not represented as original +work. Every entry records the immutable upstream commit, source path, Git blob, +license, and adaptation type reviewed for this distribution. + +## Anthropic Official Plugins + +The following modified skills derive from Apache-2.0 material in +`anthropics/claude-plugins-official`: + +- `agents-md-improver` +- `agents-md-revise` +- `code-architect` +- `code-explorer` +- `code-review` +- `code-reviewer` +- `feature-dev` +- `frontend-design` + +Copyright 2026 Anthropic, PBC. Licensed under Apache-2.0. The full license is +available at `LICENSES/Apache-2.0.txt`. + +## Anthropic Skills + +The modified `mcp-builder` and `skill-creator` skills derive from Apache-2.0 +material in `anthropics/skills`. + +Copyright 2026 Anthropic, PBC. Licensed under Apache-2.0. The full license is +available at `LICENSES/Apache-2.0.txt`. + +## Anthropic Security Review + +The modified `security-review` skill derives from the MIT-licensed +`anthropics/claude-code-security-review` repository. + +Copyright 2025 Anthropic. The upstream notice is available at +`LICENSES/Anthropic-security-review-MIT.txt`. + +## Superpowers OpenCode Plugin Pattern + +The skill-path registration pattern in `.opencode/plugins/opencode-power-pack.js` +is adapted from the MIT-licensed `obra/superpowers` OpenCode plugin. + +Copyright 2025 Jesse Vincent. The upstream notice is available at +`LICENSES/Superpowers-MIT.txt`. + +## Modification Notice + +All listed skills were changed for OpenCode compatibility, consolidated into +the `SKILL.md` format, and may include additional local workflow, validation, +or safety guidance. Consult Git history for the exact local changes. diff --git a/UPSTREAMS.json b/UPSTREAMS.json new file mode 100644 index 0000000..21661ac --- /dev/null +++ b/UPSTREAMS.json @@ -0,0 +1,163 @@ +{ + "version": 1, + "components": [ + { + "name": "opencode-plugin-pattern", + "license": "MIT", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/obra/superpowers", + "commit": "6efe32c9e2dd002d0c394e861e0529675d1ab32e", + "committedAt": "2026-04-24T02:02:37Z", + "path": ".opencode/plugins/superpowers.js", + "blob": "48a2b72ddc5ac05718d23647a11b6b169a9a6363" + } + } + ], + "skills": [ + { + "name": "agents-md-improver", + "license": "Apache-2.0", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/claude-md-management/skills/claude-md-improver/SKILL.md", + "blob": "744444e4df385e9b9160e23fba02321062dfba9a" + } + }, + { + "name": "agents-md-revise", + "license": "Apache-2.0", + "adaptation": "translated", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/claude-md-management/commands/revise-claude-md.md", + "blob": "b7f201db19ec485271945e350914e6ac5a8957bd" + } + }, + { + "name": "code-architect", + "license": "Apache-2.0", + "adaptation": "ported", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/feature-dev/agents/code-architect.md", + "blob": "fcb78bfd11004048fa287ac52c55eb5c17855549" + } + }, + { + "name": "code-explorer", + "license": "Apache-2.0", + "adaptation": "ported", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/feature-dev/agents/code-explorer.md", + "blob": "e0f667ef65f7204399110214defd46ce062a1a51" + } + }, + { + "name": "code-review", + "license": "Apache-2.0", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/code-review/commands/code-review.md", + "blob": "c46e327f19b6bb59dbf9060e8c9961e701908350" + } + }, + { + "name": "code-reviewer", + "license": "Apache-2.0", + "adaptation": "ported", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/feature-dev/agents/code-reviewer.md", + "blob": "7fb589cbd7140152fae41720e391290ba202e57e" + } + }, + { + "name": "feature-dev", + "license": "Apache-2.0", + "adaptation": "ported", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/feature-dev/commands/feature-dev.md", + "blob": "8bdeda3430e43afddbee79830db0f6ea9dfbf36a" + } + }, + { + "name": "frontend-design", + "license": "Apache-2.0", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-plugins-official", + "commit": "bdca23e8e46f8832d0030c05804ae207786ae37f", + "committedAt": "2026-04-24T19:52:02Z", + "path": "plugins/frontend-design/skills/frontend-design/SKILL.md", + "blob": "600b6db41fac7e2081c7528ec6982960892c819d" + } + }, + { + "name": "mcp-builder", + "license": "Apache-2.0", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/skills", + "commit": "5128e1865d670f5d6c9cef000e6dfc4e951fb5b9", + "committedAt": "2026-04-23T17:07:18Z", + "path": "skills/mcp-builder/SKILL.md", + "blob": "8a1a77a47d141967b246adb4da4f91037578ff7d" + } + }, + { + "name": "security-review", + "license": "MIT", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/claude-code-security-review", + "commit": "0c6a49f1fa56a1d472575da86a94dbc1edb78eda", + "committedAt": "2026-02-11T18:01:23Z", + "path": ".claude/commands/security-review.md", + "blob": "93651ea8b92194a1f739eaf5115ea493746df300" + } + }, + { + "name": "skill-creator", + "license": "Apache-2.0", + "adaptation": "adapted", + "reviewedAt": "2026-07-27", + "source": { + "repository": "https://github.com/anthropics/skills", + "commit": "5128e1865d670f5d6c9cef000e6dfc4e951fb5b9", + "committedAt": "2026-04-23T17:07:18Z", + "path": "skills/skill-creator/SKILL.md", + "blob": "65b3a402dbd09b8e83f9d637c6b553875189085c" + } + } + ] +} diff --git a/commands/agents-md-improver.md b/commands/agents-md-improver.md index ad4bcbb..787a4ed 100644 --- a/commands/agents-md-improver.md +++ b/commands/agents-md-improver.md @@ -1,5 +1,6 @@ --- description: Audit and improve project-rules files (AGENTS.md, CLAUDE.md, .agents/instructions, local overrides) so the agent keeps accurate project context. Use when the user asks to check, audit, review, update, improve, or fix their AGENTS.md or CLAUDE.md, mentions "project rules maintenance" or "agent context optimization", or when the codebase has changed enough that the rules file may be stale. Scans the repository for every rules file, grades each against a quality rubric, outputs a quality report, and applies targeted edits only after user approval. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # AGENTS.md / CLAUDE.md Improver diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md index 5e55c4d..3ca925c 100644 --- a/commands/agents-md-revise.md +++ b/commands/agents-md-revise.md @@ -1,5 +1,6 @@ --- description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # AGENTS.md / CLAUDE.md Revise diff --git a/commands/code-architect.md b/commands/code-architect.md index 04241ef..e2c3c67 100644 --- a/commands/code-architect.md +++ b/commands/code-architect.md @@ -1,5 +1,6 @@ --- description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Architect diff --git a/commands/code-explorer.md b/commands/code-explorer.md index dcd27e8..fcb15c9 100644 --- a/commands/code-explorer.md +++ b/commands/code-explorer.md @@ -1,5 +1,6 @@ --- description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Explorer diff --git a/commands/code-review.md b/commands/code-review.md index 6a235ec..a7f2f8e 100644 --- a/commands/code-review.md +++ b/commands/code-review.md @@ -1,5 +1,6 @@ --- description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Review diff --git a/commands/code-reviewer.md b/commands/code-reviewer.md index 4f2302e..5004c01 100644 --- a/commands/code-reviewer.md +++ b/commands/code-reviewer.md @@ -1,5 +1,6 @@ --- description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Reviewer diff --git a/commands/feature-dev.md b/commands/feature-dev.md index c999a89..a67903a 100644 --- a/commands/feature-dev.md +++ b/commands/feature-dev.md @@ -1,5 +1,6 @@ --- description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Feature Development diff --git a/commands/frontend-design.md b/commands/frontend-design.md index 9f372b1..a6fc9e0 100644 --- a/commands/frontend-design.md +++ b/commands/frontend-design.md @@ -1,5 +1,6 @@ --- description: Create distinctive, production-grade frontend interfaces with high design quality and accessible markup. Use this skill when the user asks to build or beautify web components, pages, applications, landing pages, dashboards, artifacts, or React/HTML/CSS UI. Generates creative, polished code that avoids generic AI aesthetics, then self-checks it against an objective accessibility and quality rubric. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices, then audit it against the self-critique rubric before returning. diff --git a/commands/mcp-builder.md b/commands/mcp-builder.md index 6a6f42a..955803b 100644 --- a/commands/mcp-builder.md +++ b/commands/mcp-builder.md @@ -1,5 +1,6 @@ --- description: Guide the creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when the user wants to build an MCP server to integrate an external API or service, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). +license: Apache-2.0 (modified; see UPSTREAMS.json) --- ## Overview @@ -145,7 +146,7 @@ Create an XML file with this structure: ## Notes -This is a port of the upstream `mcp-builder` skill from `anthropics/skills`. The original ships bundled reference files (`reference/mcp_best_practices.md`, `reference/node_mcp_server.md`, `reference/python_mcp_server.md`, `reference/evaluation.md`) which are not included in this port. When you need deeper detail, fetch them directly from . +This is a modified port of the upstream `mcp-builder` skill from `anthropics/skills`. The original ships bundled reference files (`reference/mcp_best_practices.md`, `reference/node_mcp_server.md`, `reference/python_mcp_server.md`, `reference/evaluation.md`) which are not included in this port. The reviewed upstream snapshot is pinned in `UPSTREAMS.json`. --- diff --git a/commands/security-review.md b/commands/security-review.md index 528891c..950b3fd 100644 --- a/commands/security-review.md +++ b/commands/security-review.md @@ -1,5 +1,6 @@ --- description: Perform a focused security review of pending git changes to identify high-confidence security vulnerabilities with real exploitation potential. Use this skill when the user asks for a security review, security audit, vulnerability scan, or wants to check pending changes on a branch for security issues before merging. This is NOT a general code review. +license: MIT (modified; see UPSTREAMS.json) --- # Security Review diff --git a/commands/skill-creator.md b/commands/skill-creator.md index 96bb4d1..80e4473 100644 --- a/commands/skill-creator.md +++ b/commands/skill-creator.md @@ -1,5 +1,6 @@ --- description: Create new skills (SKILL.md files), modify and improve existing skills, and design skill descriptions for accurate triggering. Use when the user wants to create a new skill from scratch, edit an existing skill, optimize a skill's description, or convert a workflow they just demonstrated into a reusable skill. +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Skill Creator @@ -151,7 +152,7 @@ The `description` field is the primary mechanism that determines whether the mod ## Notes -This is an adapted port of `anthropics/skills/skills/skill-creator`. The upstream version ships bundled scripts and an HTML eval viewer (`scripts/aggregate_benchmark.py`, `eval-viewer/generate_review.py`, etc.) that are not included here. For automated benchmarking infrastructure, see . +This is a modified port of `anthropics/skills/skills/skill-creator`. The upstream version ships bundled scripts and an HTML eval viewer (`scripts/aggregate_benchmark.py`, `eval-viewer/generate_review.py`, etc.) that are not included here. The reviewed upstream snapshot is pinned in `UPSTREAMS.json`. --- diff --git a/package.json b/package.json index b13c20c..9614362 100644 --- a/package.json +++ b/package.json @@ -8,12 +8,15 @@ "skills", "commands", ".opencode", - "assets" + "assets", + "UPSTREAMS.json", + "THIRD_PARTY_NOTICES.md", + "LICENSES" ], "scripts": { "test": "node --test" }, - "license": "MIT", + "license": "MIT AND Apache-2.0", "author": "Wayner Barrios", "repository": { "type": "git", diff --git a/skills/agents-md-improver/SKILL.md b/skills/agents-md-improver/SKILL.md index 26104dc..1431878 100644 --- a/skills/agents-md-improver/SKILL.md +++ b/skills/agents-md-improver/SKILL.md @@ -1,7 +1,7 @@ --- name: agents-md-improver description: Audit and improve project-rules files (AGENTS.md, CLAUDE.md, .agents/instructions, local overrides) so the agent keeps accurate project context. Use when the user asks to check, audit, review, update, improve, or fix their AGENTS.md or CLAUDE.md, mentions "project rules maintenance" or "agent context optimization", or when the codebase has changed enough that the rules file may be stale. Scans the repository for every rules file, grades each against a quality rubric, outputs a quality report, and applies targeted edits only after user approval. -license: MIT (adapted from anthropics/claude-plugins-official/plugins/claude-md-management/skills/claude-md-improver) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # AGENTS.md / CLAUDE.md Improver diff --git a/skills/agents-md-revise/SKILL.md b/skills/agents-md-revise/SKILL.md index 7721aab..ef616dc 100644 --- a/skills/agents-md-revise/SKILL.md +++ b/skills/agents-md-revise/SKILL.md @@ -1,7 +1,7 @@ --- name: agents-md-revise description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. -license: MIT (translated from anthropics/claude-plugins-official/plugins/claude-md-management/commands/revise-claude-md.md) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # AGENTS.md / CLAUDE.md Revise diff --git a/skills/code-architect/SKILL.md b/skills/code-architect/SKILL.md index 28a1d37..2ccfcc0 100644 --- a/skills/code-architect/SKILL.md +++ b/skills/code-architect/SKILL.md @@ -1,7 +1,7 @@ --- name: code-architect description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. -license: MIT (ported from anthropics/claude-code/plugins/feature-dev/agents/code-architect) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Architect diff --git a/skills/code-explorer/SKILL.md b/skills/code-explorer/SKILL.md index b7b14f5..ad93e75 100644 --- a/skills/code-explorer/SKILL.md +++ b/skills/code-explorer/SKILL.md @@ -1,7 +1,7 @@ --- name: code-explorer description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". -license: MIT (ported from anthropics/claude-code/plugins/feature-dev/agents/code-explorer) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Explorer diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 3dbb3d2..2bc3c41 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,7 +1,7 @@ --- name: code-review description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. -license: MIT (ported from anthropics/claude-code/plugins/code-review) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Review diff --git a/skills/code-reviewer/SKILL.md b/skills/code-reviewer/SKILL.md index ab1d114..bc2b65f 100644 --- a/skills/code-reviewer/SKILL.md +++ b/skills/code-reviewer/SKILL.md @@ -1,7 +1,7 @@ --- name: code-reviewer description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. -license: MIT (ported from anthropics/claude-code/plugins/feature-dev/agents/code-reviewer) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Code Reviewer diff --git a/skills/feature-dev/SKILL.md b/skills/feature-dev/SKILL.md index f73d024..ead5bea 100644 --- a/skills/feature-dev/SKILL.md +++ b/skills/feature-dev/SKILL.md @@ -1,7 +1,7 @@ --- name: feature-dev description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. -license: MIT (ported from anthropics/claude-code/plugins/feature-dev) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Feature Development diff --git a/skills/frontend-design/SKILL.md b/skills/frontend-design/SKILL.md index c5688ed..f65a72e 100644 --- a/skills/frontend-design/SKILL.md +++ b/skills/frontend-design/SKILL.md @@ -1,7 +1,7 @@ --- name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality and accessible markup. Use this skill when the user asks to build or beautify web components, pages, applications, landing pages, dashboards, artifacts, or React/HTML/CSS UI. Generates creative, polished code that avoids generic AI aesthetics, then self-checks it against an objective accessibility and quality rubric. -license: MIT (adapted from anthropics/claude-code/plugins/frontend-design) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices, then audit it against the self-critique rubric before returning. diff --git a/skills/mcp-builder/SKILL.md b/skills/mcp-builder/SKILL.md index 90f6fa1..b395174 100644 --- a/skills/mcp-builder/SKILL.md +++ b/skills/mcp-builder/SKILL.md @@ -1,7 +1,7 @@ --- name: mcp-builder description: Guide the creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when the user wants to build an MCP server to integrate an external API or service, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). -license: MIT (copied from anthropics/skills/skills/mcp-builder) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- ## Overview @@ -147,4 +147,4 @@ Create an XML file with this structure: ## Notes -This is a port of the upstream `mcp-builder` skill from `anthropics/skills`. The original ships bundled reference files (`reference/mcp_best_practices.md`, `reference/node_mcp_server.md`, `reference/python_mcp_server.md`, `reference/evaluation.md`) which are not included in this port. When you need deeper detail, fetch them directly from . +This is a modified port of the upstream `mcp-builder` skill from `anthropics/skills`. The original ships bundled reference files (`reference/mcp_best_practices.md`, `reference/node_mcp_server.md`, `reference/python_mcp_server.md`, `reference/evaluation.md`) which are not included in this port. The reviewed upstream snapshot is pinned in `UPSTREAMS.json`. diff --git a/skills/security-review/SKILL.md b/skills/security-review/SKILL.md index b450d2d..129591d 100644 --- a/skills/security-review/SKILL.md +++ b/skills/security-review/SKILL.md @@ -1,7 +1,7 @@ --- name: security-review description: Perform a focused security review of pending git changes to identify high-confidence security vulnerabilities with real exploitation potential. Use this skill when the user asks for a security review, security audit, vulnerability scan, or wants to check pending changes on a branch for security issues before merging. This is NOT a general code review. -license: MIT (ported from anthropics/claude-code-security-review/.claude/commands/security-review.md) +license: MIT (modified; see UPSTREAMS.json) --- # Security Review diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md index 4ecfd39..280f830 100644 --- a/skills/skill-creator/SKILL.md +++ b/skills/skill-creator/SKILL.md @@ -1,7 +1,7 @@ --- name: skill-creator description: Create new skills (SKILL.md files), modify and improve existing skills, and design skill descriptions for accurate triggering. Use when the user wants to create a new skill from scratch, edit an existing skill, optimize a skill's description, or convert a workflow they just demonstrated into a reusable skill. -license: MIT (adapted from anthropics/skills/skills/skill-creator) +license: Apache-2.0 (modified; see UPSTREAMS.json) --- # Skill Creator @@ -153,4 +153,4 @@ The `description` field is the primary mechanism that determines whether the mod ## Notes -This is an adapted port of `anthropics/skills/skills/skill-creator`. The upstream version ships bundled scripts and an HTML eval viewer (`scripts/aggregate_benchmark.py`, `eval-viewer/generate_review.py`, etc.) that are not included here. For automated benchmarking infrastructure, see . +This is a modified port of `anthropics/skills/skills/skill-creator`. The upstream version ships bundled scripts and an HTML eval viewer (`scripts/aggregate_benchmark.py`, `eval-viewer/generate_review.py`, etc.) that are not included here. The reviewed upstream snapshot is pinned in `UPSTREAMS.json`. diff --git a/tests/provenance.test.mjs b/tests/provenance.test.mjs new file mode 100644 index 0000000..9e86122 --- /dev/null +++ b/tests/provenance.test.mjs @@ -0,0 +1,73 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, readFileSync, readdirSync } from "node:fs"; +import { join } from "node:path"; + +const REPO = process.env.REPO || process.cwd(); +const manifestPath = join(REPO, "UPSTREAMS.json"); +const COMMIT_RE = /^[0-9a-f]{40}$/; +const REVIEW_DATE_RE = /^\d{4}-\d{2}-\d{2}$/; + +function frontmatter(file) { + const text = readFileSync(file, "utf8"); + const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/); + assert.ok(match, `${file}: YAML frontmatter exists`); + return Object.fromEntries(match[1].split(/\r?\n/).map((line) => { + const separator = line.indexOf(":"); + return [line.slice(0, separator).trim(), line.slice(separator + 1).trim()]; + })); +} + +test("provenance manifest covers every shipped skill with an immutable source", () => { + assert.ok(existsSync(manifestPath), "UPSTREAMS.json exists"); + + const manifest = JSON.parse(readFileSync(manifestPath, "utf8")); + const skillNames = readdirSync(join(REPO, "skills")) + .filter((name) => existsSync(join(REPO, "skills", name, "SKILL.md"))) + .sort(); + const entries = manifest.skills.toSorted((a, b) => a.name.localeCompare(b.name)); + + assert.deepEqual(entries.map((entry) => entry.name), skillNames); + for (const entry of entries) { + assert.match(entry.source.commit, COMMIT_RE, `${entry.name}: immutable source commit`); + assert.match(entry.source.blob, COMMIT_RE, `${entry.name}: immutable source blob`); + assert.match(entry.reviewedAt, REVIEW_DATE_RE, `${entry.name}: review date`); + assert.match(entry.source.repository, /^https:\/\/github\.com\/[^/]+\/[^/]+$/); + assert.ok(entry.source.path.length > 0, `${entry.name}: source path`); + assert.ok(["Apache-2.0", "MIT"].includes(entry.license), `${entry.name}: known license`); + assert.ok(["adapted", "ported", "translated"].includes(entry.adaptation), `${entry.name}: adaptation type`); + } +}); + +test("distributed artifacts carry matching third-party license notices", () => { + const manifest = JSON.parse(readFileSync(manifestPath, "utf8")); + const packageJson = JSON.parse(readFileSync(join(REPO, "package.json"), "utf8")); + + assert.equal(packageJson.license, "MIT AND Apache-2.0"); + + for (const entry of manifest.skills) { + const expected = `${entry.license} (modified`; + const skill = frontmatter(join(REPO, "skills", entry.name, "SKILL.md")); + const command = frontmatter(join(REPO, "commands", `${entry.name}.md`)); + assert.ok(skill.license?.startsWith(expected), `${entry.name}: skill marks the source as modified`); + assert.ok(command.license?.startsWith(expected), `${entry.name}: command marks the source as modified`); + } + + for (const path of ["UPSTREAMS.json", "THIRD_PARTY_NOTICES.md", "LICENSES"]) { + assert.ok(packageJson.files.includes(path), `package includes ${path}`); + } + assert.ok(existsSync(join(REPO, "LICENSES", "Apache-2.0.txt"))); + assert.ok(existsSync(join(REPO, "LICENSES", "Anthropic-security-review-MIT.txt"))); +}); + +test("provenance includes the adapted OpenCode plugin pattern", () => { + const manifest = JSON.parse(readFileSync(manifestPath, "utf8")); + assert.ok(Array.isArray(manifest.components), "component provenance exists"); + const component = manifest.components.find((entry) => entry.name === "opencode-plugin-pattern"); + + assert.equal(component.license, "MIT"); + assert.equal(component.source.repository, "https://github.com/obra/superpowers"); + assert.match(component.source.commit, COMMIT_RE); + assert.match(component.source.blob, COMMIT_RE); + assert.ok(existsSync(join(REPO, "LICENSES", "Superpowers-MIT.txt"))); +}); From ce12c2777c37e1124eb6f4101fdfad3846b2faeb Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 27 Jul 2026 13:25:30 -0400 Subject: [PATCH 02/32] Align licensing documentation --- .opencode/plugins/opencode-power-pack.js | 7 ++-- README.md | 48 ++++++++++++------------ 2 files changed, 27 insertions(+), 28 deletions(-) diff --git a/.opencode/plugins/opencode-power-pack.js b/.opencode/plugins/opencode-power-pack.js index 78b2d1a..fd4c4fa 100644 --- a/.opencode/plugins/opencode-power-pack.js +++ b/.opencode/plugins/opencode-power-pack.js @@ -20,10 +20,9 @@ * `config` hook) is adapted directly from Jesse Vincent's superpowers * plugin: https://github.com/obra/superpowers * - * The skills under skills/ are ports/translations of artifacts originally - * written by Anthropic for Claude Code. See README.md → Acknowledgments - * and each SKILL.md's `license` frontmatter for the specific upstream of - * each skill. + * The skills under skills/ are modified upstream works. See UPSTREAMS.json + * for immutable source commits and blobs, and THIRD_PARTY_NOTICES.md for + * their licenses and attribution. * ───────────────────────────────────────────────────────────────────────── */ diff --git a/README.md b/README.md index 7fd3939..2447d4b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

- License: MIT + License: MIT and Apache-2.0 GitHub stars Last commit Issues @@ -27,7 +27,7 @@

- Built on top of anthropics/claude-code, + Built on top of anthropics/claude-plugins-official, anthropics/skills, anthropics/claude-code-security-review, and obra/superpowers. See Acknowledgments. @@ -57,34 +57,34 @@ It pairs nicely with **[obra/superpowers](https://github.com/obra/superpowers)** Review code-review -translated · plugins/code-review +adapted · claude-plugins-official/code-review Multi-agent PR review with confidence-filtered cross-checks and reproduction scenarios security-review -translated · claude-code-security-review +adapted · claude-code-security-review OWASP-bucketed, three-stage filtering, requires concrete attack PoC per finding Feature dev feature-dev -translated · plugins/feature-dev +ported · claude-plugins-official/feature-dev Seven-phase guided workflow: discovery → exploration → questions → architecture → impl → review → summary code-explorer -translated · feature-dev/agents +ported · claude-plugins-official/feature-dev Deep codebase analysis sub-task — traces a feature end-to-end code-architect -translated · feature-dev/agents +ported · claude-plugins-official/feature-dev Decisive architecture blueprint sub-task with file-level implementation map code-reviewer -translated · feature-dev/agents +ported · claude-plugins-official/feature-dev Two-pass adversarial review sub-task with explicit edge-case checklist Design frontend-design -copied · plugins/frontend-design +adapted · claude-plugins-official/frontend-design Distinctive, production-grade UI generation that avoids generic AI aesthetics Authoring mcp-builder -copied · skills/mcp-builder +adapted · anthropics/skills/mcp-builder Build high-quality MCP servers (Python or TypeScript) skill-creator adapted · skills/skill-creator @@ -149,10 +149,10 @@ If you already use other plugins (e.g. `superpowers`), keep all of them in the a } ``` -To pin a specific tag (recommended once releases exist): +To pin a specific published tag: ```jsonc -"opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git#v0.2.0" +"opencode-power-pack@git+https://github.com/waybarrios/opencode-power-pack.git#" ``` You still need a local copy of the repo for **step 2** (the slash command files live there). Clone it next to wherever you keep code: @@ -267,7 +267,7 @@ pkill -f opencode opencode ``` -If you pinned a version in `opencode.json` (e.g. `#v0.2.0`), bump the tag in the JSON before restarting, otherwise OpenCode keeps using the pinned commit. +If you pinned a version in `opencode.json`, bump the tag in the JSON before restarting, otherwise OpenCode keeps using the pinned commit. --- @@ -386,7 +386,7 @@ The plugin entry-point only registers the skills path. Slash commands are **phys |---|---| | Porting Claude Code skills where the methodology is portable | Claude Code slash commands ported as Claude-Code-style commands | | Translating commands and agents into SKILL.md format | Claude Code hooks | -| Direct copies of `anthropics/skills` skills with attribution | Claude Code output styles | +| Licensed adaptations of upstream skills with immutable provenance | Claude Code output styles | | OpenCode-native slash commands generated from skills | Anything that breaks if you also use Claude Code | --- @@ -411,19 +411,19 @@ Skill format must follow the OpenCode spec: ## Acknowledgments -**This package is not original work.** Almost everything in `skills/` is either a direct copy or a translation of skills, commands, or agent definitions written by **Anthropic** for Claude Code, plus one direct adaptation of the OpenCode plugin pattern from **Jesse Vincent (obra)**. The credit belongs to them; this repo's contribution is the *porting and packaging* for OpenCode. +**The bundled skills are modified upstream works.** Most content in `skills/` is adapted from skills, commands, or agent definitions written by **Anthropic**, plus an adaptation of the OpenCode plugin pattern from **Jesse Vincent (obra)**. This repository contributes the OpenCode port, packaging, and additional workflow guidance. Exact sources and Git blobs are recorded in [`UPSTREAMS.json`](UPSTREAMS.json). ### Upstream sources | Upstream | Project | What we use from it | |---|---|---| -| Anthropic | [`anthropics/claude-code/plugins/code-review`](https://github.com/anthropics/claude-code/tree/main/plugins/code-review) | The four-reviewer parallel-review methodology that became `code-review` | -| Anthropic | [`anthropics/claude-code/plugins/feature-dev`](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev) | The seven-phase workflow and the three sub-agents (`code-explorer`, `code-architect`, `code-reviewer`) | -| Anthropic | [`anthropics/claude-code/plugins/frontend-design`](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) | The `frontend-design` skill (direct copy) | -| Anthropic | [`anthropics/claude-code-security-review`](https://github.com/anthropics/claude-code-security-review) | The `/security-review` slash command, translated and extended | -| Anthropic | [`anthropics/skills/skills/mcp-builder`](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) | The `mcp-builder` skill (direct copy, references stripped) | -| Anthropic | [`anthropics/skills/skills/skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator) | The `skill-creator` skill (adapted, eval-tooling references trimmed) | -| Anthropic | [`anthropics/claude-plugins-official/.../claude-md-management`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management) | Renamed to `agents-md-improver` and `agents-md-revise`; covers AGENTS.md too | +| Anthropic | [`claude-plugins-official/code-review`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/code-review) | The confidence-filtered parallel-review methodology adapted as `code-review` | +| Anthropic | [`claude-plugins-official/feature-dev`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/feature-dev) | The seven-phase workflow and three specialist roles | +| Anthropic | [`claude-plugins-official/frontend-design`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/frontend-design) | The base `frontend-design` methodology, substantially extended here | +| Anthropic | [`claude-code-security-review`](https://github.com/anthropics/claude-code-security-review/tree/0c6a49f1fa56a1d472575da86a94dbc1edb78eda) | The MIT security-review command, translated and extended | +| Anthropic | [`anthropics/skills/mcp-builder`](https://github.com/anthropics/skills/tree/5128e1865d670f5d6c9cef000e6dfc4e951fb5b9/skills/mcp-builder) | The base `mcp-builder` workflow, adapted without its original resources | +| Anthropic | [`anthropics/skills/skill-creator`](https://github.com/anthropics/skills/tree/5128e1865d670f5d6c9cef000e6dfc4e951fb5b9/skills/skill-creator) | The `skill-creator` workflow, adapted without its original eval tooling | +| Anthropic | [`claude-plugins-official/claude-md-management`](https://github.com/anthropics/claude-plugins-official/tree/bdca23e8e46f8832d0030c05804ae207786ae37f/plugins/claude-md-management) | The base project-memory workflows, expanded to cover AGENTS.md | | Jesse Vincent (obra) | [`obra/superpowers`](https://github.com/obra/superpowers) | The OpenCode plugin pattern (`config.skills.paths.push(...)`) used in `.opencode/plugins/opencode-power-pack.js` | ### What this repo actually contributes @@ -433,10 +433,10 @@ Skill format must follow the OpenCode spec: - Deepening the review skills (`code-review`, `code-reviewer`, `security-review`) with extra reviewers, multi-pass adversarial analysis, mandatory category coverage, and concrete-PoC requirements — the originals were already strong; the ports try to compensate for the smaller models people sometimes run under OpenCode by being more directive - Bundling everything as a one-line OpenCode plugin, plus generating physical slash command files that inline each skill's full content -Each individual SKILL.md frontmatter includes a `license` field naming its specific upstream. The wrapper code (the plugin JS, the README, the LICENSE) is the only original-work portion of this repo. +Each `SKILL.md` and generated command marks itself as modified and names its license. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for attribution and `UPSTREAMS.json` for immutable provenance. If you are one of the upstream authors and you'd like the attribution worded differently — or removed — open an issue and we'll fix it. ## License -MIT for the wrapper code and original work in this repo. Each ported skill cites its upstream source in its frontmatter; upstream Anthropic projects are also MIT-licensed. See [LICENSE](LICENSE) for full attribution. +The wrapper code and original project material are MIT-licensed under [LICENSE](LICENSE). Modified skills and command prompts derived from Anthropic's official plugins and skills are Apache-2.0, except `security-review`, whose upstream is MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), [UPSTREAMS.json](UPSTREAMS.json), and [LICENSES/](LICENSES/) for exact terms and sources. From 6e83761707c4b478276be3d426819148f52948da Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 27 Jul 2026 14:32:04 -0400 Subject: [PATCH 03/32] Register read-only workflow agents --- .opencode/plugins/agent-config.js | 65 ++++++++++++++++++++++++ .opencode/plugins/opencode-power-pack.js | 14 +++-- tests/plugin-registration.test.mjs | 53 +++++++++++++++++++ 3 files changed, 127 insertions(+), 5 deletions(-) create mode 100644 .opencode/plugins/agent-config.js create mode 100644 tests/plugin-registration.test.mjs diff --git a/.opencode/plugins/agent-config.js b/.opencode/plugins/agent-config.js new file mode 100644 index 0000000..65d1e79 --- /dev/null +++ b/.opencode/plugins/agent-config.js @@ -0,0 +1,65 @@ +import { readFileSync } from "fs"; +import path from "path"; + +const AGENT_NAMES = ["code-explorer", "code-architect", "code-reviewer"]; +const READ_ONLY_PERMISSION = { + "*": "deny", + read: { + "*": "allow", + "*.env": "deny", + "*.env.*": "deny", + "*.env.example": "allow", + }, + glob: "allow", + grep: "allow", + list: "allow", + edit: "deny", + task: "deny", + webfetch: "deny", + websearch: "deny", + external_directory: "deny", +}; +const REVIEW_BASH_PERMISSION = { + "*": "deny", + "git status*": "allow", + "git diff*": "allow", + "git show*": "allow", + "git log*": "allow", + "git blame*": "allow", + "git rev-parse*": "allow", + "git merge-base*": "allow", + "git ls-files*": "allow", + "git *--output*": "deny", + "git *--ext-diff*": "deny", + "git *>*": "deny", +}; + +function readSkill(skillsDir, name) { + const source = readFileSync(path.join(skillsDir, name, "SKILL.md"), "utf8"); + const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/); + if (!match) throw new Error(`Invalid frontmatter in ${name}/SKILL.md`); + + const description = match[1] + .split(/\r?\n/) + .find((line) => line.startsWith("description:")) + ?.slice("description:".length) + .trim(); + if (!description) throw new Error(`Missing description in ${name}/SKILL.md`); + + return { description, prompt: match[2].trim() }; +} + +export function loadAgentConfigs(skillsDir) { + return Object.fromEntries(AGENT_NAMES.map((name) => { + const skill = readSkill(skillsDir, name); + const permission = name === "code-reviewer" + ? { ...READ_ONLY_PERMISSION, bash: REVIEW_BASH_PERMISSION } + : { ...READ_ONLY_PERMISSION, bash: "deny" }; + + return [name, { + ...skill, + mode: "subagent", + permission, + }]; + })); +} diff --git a/.opencode/plugins/opencode-power-pack.js b/.opencode/plugins/opencode-power-pack.js index fd4c4fa..6531ee7 100644 --- a/.opencode/plugins/opencode-power-pack.js +++ b/.opencode/plugins/opencode-power-pack.js @@ -7,11 +7,9 @@ * mcp-builder, skill-creator, agents-md-improver, agents-md-revise) without * requiring symlinks or manual config. * - * Slash commands are NOT registered here on purpose — they are provided by - * physical markdown files under `commands/` in this repo, intended to be - * symlinked into `~/.config/opencode/commands/`. Each command file inlines - * the full SKILL.md content, so the model receives the actual workflow as - * its prompt rather than a meta-instruction telling it to load the skill. + * OpenCode 1.18.7+ exposes discovered skills as same-named slash commands. + * The plugin also registers the feature workflow's specialist roles as + * read-only subagents derived from their SKILL.md bodies. * * ──── Attribution ──────────────────────────────────────────────────────── * @@ -28,9 +26,11 @@ import path from 'path'; import { fileURLToPath } from 'url'; +import { loadAgentConfigs } from './agent-config.js'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const skillsDir = path.resolve(__dirname, '../../skills'); +const bundledAgents = loadAgentConfigs(skillsDir); export const OpencodePowerPack = async () => { return { @@ -40,6 +40,10 @@ export const OpencodePowerPack = async () => { if (!config.skills.paths.includes(skillsDir)) { config.skills.paths.push(skillsDir); } + config.agent = config.agent || {}; + for (const [name, agent] of Object.entries(bundledAgents)) { + if (!config.agent[name]) config.agent[name] = agent; + } }, }; }; diff --git a/tests/plugin-registration.test.mjs b/tests/plugin-registration.test.mjs new file mode 100644 index 0000000..b40bcff --- /dev/null +++ b/tests/plugin-registration.test.mjs @@ -0,0 +1,53 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { OpencodePowerPack } from "../.opencode/plugins/opencode-power-pack.js"; + +test("plugin registers the feature workflow roles as read-only subagents", async () => { + const plugin = await OpencodePowerPack(); + const config = {}; + + await plugin.config(config); + + for (const name of ["code-explorer", "code-architect", "code-reviewer"]) { + const agent = config.agent?.[name]; + assert.ok(agent, `${name} is registered`); + assert.equal(agent.mode, "subagent"); + assert.equal(agent.permission.edit, "deny"); + assert.equal(agent.permission.task, "deny"); + assert.equal(agent.permission.webfetch, "deny"); + assert.deepEqual(agent.permission.read, { + "*": "allow", + "*.env": "deny", + "*.env.*": "deny", + "*.env.example": "allow", + }); + assert.match(agent.description, /\S/); + assert.match(agent.prompt, /\S/); + assert.doesNotMatch(agent.prompt, /^---/); + } + + assert.deepEqual(config.agent["code-reviewer"].permission.bash, { + "*": "deny", + "git status*": "allow", + "git diff*": "allow", + "git show*": "allow", + "git log*": "allow", + "git blame*": "allow", + "git rev-parse*": "allow", + "git merge-base*": "allow", + "git ls-files*": "allow", + "git *--output*": "deny", + "git *--ext-diff*": "deny", + "git *>*": "deny", + }); +}); + +test("plugin preserves user-defined agents with the same names", async () => { + const plugin = await OpencodePowerPack(); + const customReviewer = { description: "My reviewer", mode: "subagent" }; + const config = { agent: { "code-reviewer": customReviewer } }; + + await plugin.config(config); + + assert.equal(config.agent["code-reviewer"], customReviewer); +}); From c753cd35adf97d444f9e3e863f08a938053d92b5 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 27 Jul 2026 14:32:22 -0400 Subject: [PATCH 04/32] Adopt native skill discovery --- .github/workflows/opencode-smoke.yml | 22 +++ THIRD_PARTY_NOTICES.md | 8 +- commands/agents-md-improver.md | 183 ------------------------- commands/agents-md-revise.md | 97 ------------- commands/code-architect.md | 59 -------- commands/code-explorer.md | 59 -------- commands/code-review.md | 135 ------------------ commands/code-reviewer.md | 117 ---------------- commands/feature-dev.md | 111 --------------- commands/frontend-design.md | 92 ------------- commands/mcp-builder.md | 153 --------------------- commands/security-review.md | 196 --------------------------- commands/skill-creator.md | 159 ---------------------- package.json | 8 +- scripts/opencode-smoke.mjs | 169 +++++++++++++++++++++++ tests/agents-md-revise.test.mjs | 6 - tests/frontend-design.test.mjs | 8 -- tests/opencode-smoke.test.mjs | 34 +++++ tests/package-surface.test.mjs | 38 ++++++ tests/provenance.test.mjs | 2 - tests/skill-lint.test.mjs | 14 -- tests/working-discipline.test.mjs | 4 - 22 files changed, 273 insertions(+), 1401 deletions(-) create mode 100644 .github/workflows/opencode-smoke.yml delete mode 100644 commands/agents-md-improver.md delete mode 100644 commands/agents-md-revise.md delete mode 100644 commands/code-architect.md delete mode 100644 commands/code-explorer.md delete mode 100644 commands/code-review.md delete mode 100644 commands/code-reviewer.md delete mode 100644 commands/feature-dev.md delete mode 100644 commands/frontend-design.md delete mode 100644 commands/mcp-builder.md delete mode 100644 commands/security-review.md delete mode 100644 commands/skill-creator.md create mode 100644 scripts/opencode-smoke.mjs create mode 100644 tests/opencode-smoke.test.mjs create mode 100644 tests/package-surface.test.mjs diff --git a/.github/workflows/opencode-smoke.yml b/.github/workflows/opencode-smoke.yml new file mode 100644 index 0000000..5b48fa1 --- /dev/null +++ b/.github/workflows/opencode-smoke.yml @@ -0,0 +1,22 @@ +name: OpenCode smoke + +on: + pull_request: + paths: + - ".opencode/**" + - "skills/**" + - "scripts/opencode-smoke.mjs" + - "package.json" + - ".github/workflows/opencode-smoke.yml" + workflow_dispatch: + +jobs: + opencode-1-18-7: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "24" + - run: node scripts/opencode-smoke.mjs 1.18.7 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index c10b4b9..34d1201 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -4,10 +4,10 @@ The repository wrapper, plugin integration, packaging, tests, and original documentation are licensed under the root MIT `LICENSE` unless a file states otherwise. -The skills and generated command prompts are modified derivatives of the -sources recorded in `UPSTREAMS.json`. They are not represented as original -work. Every entry records the immutable upstream commit, source path, Git blob, -license, and adaptation type reviewed for this distribution. +The skills are modified derivatives of the sources recorded in +`UPSTREAMS.json`. They are not represented as original work. Every entry +records the immutable upstream commit, source path, Git blob, license, and +adaptation type reviewed for this distribution. ## Anthropic Official Plugins diff --git a/commands/agents-md-improver.md b/commands/agents-md-improver.md deleted file mode 100644 index 787a4ed..0000000 --- a/commands/agents-md-improver.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -description: Audit and improve project-rules files (AGENTS.md, CLAUDE.md, .agents/instructions, local overrides) so the agent keeps accurate project context. Use when the user asks to check, audit, review, update, improve, or fix their AGENTS.md or CLAUDE.md, mentions "project rules maintenance" or "agent context optimization", or when the codebase has changed enough that the rules file may be stale. Scans the repository for every rules file, grades each against a quality rubric, outputs a quality report, and applies targeted edits only after user approval. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Improver - -Audit, evaluate, and improve project-rules files across a codebase to ensure the agent has optimal project context. - -OpenCode resolves project rules **first-match-wins per directory**: when a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. Resolution walks from the working directory up to the git root, takes the first match at each level, and merges those with the global `~/.config/opencode/AGENTS.md` and any paths declared in the `instructions` field of `opencode.json`. Treat `AGENTS.md` as canonical when creating new files, and report any directory that contains both files as a finding, since its `CLAUDE.md` is silently ignored. - -**This skill can write to project-rules files.** After presenting a quality report and getting user approval, it updates the files with targeted improvements. - -## Workflow - -### Phase 1: Discovery - -Find all relevant files in the repository: - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" -o -name ".agents.local.md" \) 2>/dev/null | head -50 -``` - -**File types and locations:** - -| Type | Location | Purpose | -|------|----------|---------| -| Project root (OpenCode native) | `./AGENTS.md` | Primary project context (committed, shared) | -| Project root (Claude compat) | `./CLAUDE.md` | Same purpose; OpenCode reads it as fallback | -| Local overrides | `./.agents.local.md` or `./.claude.local.md` | Personal/local settings (gitignored) | -| Global defaults | `~/.config/opencode/AGENTS.md` or `~/.claude/CLAUDE.md` | User-wide defaults | -| Package-specific | `./packages/*/AGENTS.md` | Module-level context in monorepos | -| Subdirectory | Any nested location | Feature/domain-specific context | - -OpenCode walks up from the working directory toward the git root, loading any matching rules files along the way, so monorepos and nested projects work automatically. - -### Phase 2: Quality assessment - -For each rules file, evaluate against the criteria below. - -**Quick assessment checklist:** - -| Criterion | Weight | Check | -|-----------|--------|-------| -| Commands / workflows documented | High | Are build / test / deploy commands present? | -| Architecture clarity | High | Can the agent understand the codebase structure? | -| Non-obvious patterns | Medium | Are gotchas and quirks documented? | -| Conciseness | Medium | No verbose explanations or obvious info? | -| Currency | High | Does it reflect the current codebase state? | -| Actionability | High | Are instructions executable, not vague? | - -**Quality scores:** - -- **A (90–100)** — Comprehensive, current, actionable. -- **B (70–89)** — Good coverage, minor gaps. -- **C (50–69)** — Basic info, missing key sections. -- **D (30–49)** — Sparse or outdated. -- **F (0–29)** — Missing or severely outdated. - -### Phase 3: Quality-report output - -**Always output the quality report BEFORE making any updates.** - -Format: - -``` -## Project-Rules Quality Report - -### Summary -- Files found: X -- Average score: X/100 -- Files needing update: X - -### File-by-File Assessment - -#### 1. ./AGENTS.md (Project Root) -**Score: XX/100 (Grade: X)** - -| Criterion | Score | Notes | -|-----------|-------|-------| -| Commands / workflows | X/20 | ... | -| Architecture clarity | X/20 | ... | -| Non-obvious patterns | X/15 | ... | -| Conciseness | X/15 | ... | -| Currency | X/15 | ... | -| Actionability | X/15 | ... | - -**Issues:** -- [List specific problems] - -**Recommended additions:** -- [List what should be added] - -#### 2. ./packages/api/AGENTS.md (Package-specific) -... -``` - -### Phase 4: Targeted updates - -After the quality report, ask the user for confirmation before updating. - -**Update guidelines (critical):** - -1. **Propose targeted additions only.** Focus on genuinely useful info: - - Commands or workflows discovered during analysis - - Gotchas or non-obvious patterns found in code - - Package relationships that were unclear - - Testing approaches that work - - Configuration quirks - -2. **Keep it minimal.** Avoid: - - Restating what is obvious from the code - - Generic best practices already covered - - One-off fixes unlikely to recur - - Verbose explanations when a one-liner suffices - -3. **Show diffs.** For each change, show: - - Which file to update - - The specific addition (diff or quoted block) - - A brief explanation of why this helps future sessions - -**Diff format:** - -````markdown -### Update: ./AGENTS.md - -**Why:** Build command was missing, causing confusion about how to run the project. - -```diff -+ ## Quick Start -+ -+ ```bash -+ npm install -+ npm run dev # Start development server on port 3000 -+ ``` -``` -```` - -### Phase 5: Apply updates - -After user approval, apply changes using the editor tool. Preserve the existing content structure; only add what was approved. - -## Common issues to flag - -1. **Stale commands** — build commands that no longer work. -2. **Missing dependencies** — required tools not mentioned. -3. **Outdated architecture** — file structure that has changed. -4. **Missing environment setup** — required env vars or config. -5. **Broken test commands** — test scripts that have changed. -6. **Undocumented gotchas** — non-obvious patterns not captured. -7. **Shadowed `CLAUDE.md`** — a directory that contains both `AGENTS.md` and `CLAUDE.md`. OpenCode loads only `AGENTS.md`, so the `CLAUDE.md` is silently ignored; merge its contents into `AGENTS.md` or remove it. - -## What makes a great rules file - -**Key principles:** - -- Concise and human-readable. -- Actionable commands that can be copy-pasted. -- Project-specific patterns, not generic advice. -- Non-obvious gotchas and warnings. - -**Recommended sections** (use only what is relevant): - -- Commands (build, test, dev, lint) -- Architecture (directory structure) -- Key files (entry points, config) -- Code style (project conventions) -- Environment (required vars, setup) -- Testing (commands, patterns) -- Gotchas (quirks, common mistakes) -- Workflow (when to do what) - -## Tips to share with the user - -- **Keep it concise** — the rules file is part of the prompt, so brevity matters. Dense is better than verbose. -- **Actionable commands** — all documented commands should be copy-paste ready. -- **Use a `.local` override** — for personal preferences not shared with the team (add to `.gitignore`). -- **Global defaults** — put user-wide preferences in `~/.config/opencode/AGENTS.md` (or `~/.claude/CLAUDE.md`). -- **Prefer `AGENTS.md`.** Use `AGENTS.md` for new rules files: OpenCode reads it natively and Claude Code reads it as a fallback. Do not add an `AGENTS.md` alongside an existing `CLAUDE.md` — under first-match-wins, OpenCode would load only the `AGENTS.md` and ignore the `CLAUDE.md` entirely. Either keep maintaining the `CLAUDE.md` in place, or migrate its contents into `AGENTS.md` and remove it. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md deleted file mode 100644 index 3ca925c..0000000 --- a/commands/agents-md-revise.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Revise - -Review the current session for learnings about working in this codebase, then update the project-rules file with context that would help future sessions be more effective. - -OpenCode resolves project rules first-match-wins per directory: if a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. When capturing learnings, prefer `AGENTS.md` for a new file; if both already exist in the same directory, write to `AGENTS.md` — never into the shadowed `CLAUDE.md`, or the notes land in a file OpenCode ignores. If only `CLAUDE.md` exists, update it in place (and consider migrating it to `AGENTS.md`). - -## Step 1 — Reflect - -Look back over the session and identify what context was missing that would have helped the agent work more effectively. Examples: - -- Bash commands that were used or discovered -- Code-style patterns followed -- Testing approaches that worked -- Environment / configuration quirks -- Warnings or gotchas encountered -- Build steps that surprised you -- Tool versions that mattered -- Project-specific conventions that took time to figure out - -Be selective. Only capture things that: - -1. Will recur in future sessions (not one-off fixes). -2. Would have saved time if known up front. -3. Cannot be derived by reading the code. - -## Step 2 — Find rules files - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".agents.local.md" -o -name ".claude.local.md" \) 2>/dev/null | head -20 -``` - -Decide where each addition belongs: - -- **`AGENTS.md` / `CLAUDE.md`** — team-shared, committed to git. Use for project-wide conventions, build commands, architectural notes. -- **`.agents.local.md` / `.claude.local.md`** — personal / local only, gitignored. Use for personal preferences that should not affect teammates. - -If both `AGENTS.md` and `CLAUDE.md` exist in the same directory, target `AGENTS.md` — OpenCode ignores the co-located `CLAUDE.md`, so anything written there is lost. - -If no rules file exists yet, propose creating `AGENTS.md` at the project root. - -## Step 3 — Draft additions - -**Keep it concise.** The rules file is part of every prompt, so brevity matters. One line per concept when possible. - -Format: ` — ` - -**Avoid:** - -- Verbose explanations -- Obvious information that any reader of the code would already know -- One-off fixes unlikely to recur -- Restating what is already documented elsewhere in the rules file - -**Prefer:** - -- Imperative commands ("Run `pnpm i --frozen-lockfile` after pulling") -- Concrete gotchas ("The `dev` script binds to port 3000 — kill any other process on that port first") -- Project-specific patterns ("All dates are stored in UTC; convert at the boundary") - -## Step 4 — Show proposed changes - -For each addition, show the user the diff before applying. Format: - -````markdown -### Update: ./AGENTS.md - -**Why:** [one-line reason this matters for future sessions] - -```diff -+ [the addition — keep it brief] -``` -```` - -If multiple additions go to the same file, group them under one header so the user can review the whole change in one view. - -## Step 5 — Apply with approval - -Ask the user explicitly: *"Apply these changes?"* Edit only files they approve. - -Preserve the existing structure. Place additions in the most relevant section (e.g., a new build command goes under "Commands" if that section exists). If no obvious section fits, create one with a clear header. - -If the user rejects an addition, do not retry it in the same session — they may have a reason. Move on. - -## Notes - -- This skill **writes** to project files. Always show the diff first and wait for approval. -- Pair this skill with `agents-md-improver` for the full maintenance loop: improver audits and identifies gaps; this one captures fresh session-specific learnings. -- Do not include sensitive information (API keys, tokens, internal URLs) in committed rules files. Put those in `.agents.local.md` / `.claude.local.md` or in environment variables. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-architect.md b/commands/code-architect.md deleted file mode 100644 index e2c3c67..0000000 --- a/commands/code-architect.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Architect - -You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Core process - -### 1. Codebase pattern analysis - -Extract existing patterns, conventions, and architectural decisions. Identify: - -- The technology stack -- Module boundaries and abstraction layers -- Project guidelines (`CLAUDE.md` / `AGENTS.md`) -- Similar features already implemented — how were they structured? -- Key abstractions the codebase already provides - -### 2. Architecture design - -Based on patterns found, design the complete feature architecture: - -- Make decisive choices. Pick one approach and commit to it. -- Ensure seamless integration with existing code. -- Design for testability, performance, and maintainability. - -### 3. Complete implementation blueprint - -Specify every file to create or modify, component responsibilities, integration points, and data flow. Break the implementation into clear phases. - -## Output - -Deliver a decisive, complete architecture blueprint. Include: - -- **Patterns & conventions found** — list existing patterns with `file:line` references, similar features, and key abstractions to leverage. -- **Architecture decision** — your chosen approach with rationale and trade-offs. -- **Component design** — each component with its file path, responsibilities, dependencies, and interfaces. -- **Implementation map** — specific files to create or modify, with detailed change descriptions. -- **Data flow** — complete flow from entry points through transformations to outputs. -- **Build sequence** — phased implementation steps as a checklist. -- **Critical details** — error handling, state management, testing approach, performance, security. - -Make confident architectural choices. Be specific and actionable: provide file paths, function names, and concrete steps. Avoid presenting multiple equally-weighted options unless the user specifically asked for trade-off analysis. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-explorer.md b/commands/code-explorer.md deleted file mode 100644 index fcb15c9..0000000 --- a/commands/code-explorer.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Explorer - -You are an expert code analyst specializing in tracing and understanding feature implementations across codebases. - -## Core mission - -Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers. - -## Analysis approach - -### 1. Feature discovery - -- Find entry points: APIs, UI components, CLI commands. -- Locate core implementation files. -- Map feature boundaries and configuration surface. - -### 2. Code-flow tracing - -- Follow call chains from entry to output. -- Trace data transformations at each step. -- Identify all dependencies and integrations. -- Document state changes and side effects. - -### 3. Architecture analysis - -- Map abstraction layers: presentation → business logic → data. -- Identify design patterns and architectural decisions. -- Document interfaces between components. -- Note cross-cutting concerns: auth, logging, caching, observability. - -### 4. Implementation details - -- Key algorithms and data structures. -- Error handling and edge cases. -- Performance considerations. -- Technical debt or improvement areas. - -## Output - -Deliver a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Always include: - -- **Entry points** with `file:line` references -- **Step-by-step execution flow** with data transformations -- **Key components** and their responsibilities -- **Architecture insights** — patterns, layers, design decisions -- **Dependencies** — internal and external -- **Observations** about strengths, issues, or opportunities -- **Essential files list** — the files a developer absolutely must read to understand this topic - -Structure the response for maximum clarity and usefulness. Always cite specific file paths and line numbers. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-review.md b/commands/code-review.md deleted file mode 100644 index a7f2f8e..0000000 --- a/commands/code-review.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Review - -Provide a high-signal code review for a pull request or set of pending changes. The goal is to surface only issues that are clearly real and actionable, while filtering out noise, nitpicks, and false positives. - -## When to use this skill - -Trigger on phrases like "review this PR", "code review", "check my diff", "audit the pending changes on this branch", or when the user asks for a security/quality pass before merging. - -## High-level process - -Follow these steps in order. Use OpenCode's parallel sub-task dispatch where the original Claude Code workflow used parallel agents. - -### 1. Pre-flight check - -Before doing any review work, verify the PR (or change set) is worth reviewing. Skip the review and stop early if any of the following hold: - -- The PR is closed -- The PR is a draft -- The change is trivial (single-line typo, formatting, automated dependency bump) and obviously correct -- A previous review by the agent already exists on this PR - -Use `gh pr view ` (or the local `git diff` for non-PR review) to gather state. - -### 2. Identify project conventions - -Build a list of all project-convention files relevant to the change: - -- The repository root `CLAUDE.md` / `AGENTS.md` (whichever exists) -- Any nested `CLAUDE.md` / `AGENTS.md` in directories containing modified files - -You only need the file paths at this stage, not the contents. - -### 3. Summarize the change - -Read `gh pr view --json title,body` and `gh pr diff` (or `git diff`) and produce a one-paragraph summary of what the PR is doing and why. This grounds the rest of the review. - -### 4. Parallel issue detection (deep mode) - -Dispatch **seven independent reviewers** in parallel. Each returns a list of candidate issues, where each issue includes a description, a reason category, an initial confidence (0–100), and a one-sentence failure scenario explaining how this would manifest in practice. - -- **Reviewer 1 + Reviewer 2 — Convention compliance.** Audit the diff against the relevant `CLAUDE.md` / `AGENTS.md` rules. Only consider rule files that apply to the file being reviewed (same path or ancestor directory). Quote the exact rule being violated. -- **Reviewer 3 — Diff-only bug scan.** Scan the diff for obvious bugs without reading surrounding files. Flag only clear issues that do not need unseen context. -- **Reviewer 4 — Deep-context bug scan.** Read the **full file(s)** for each changed function, not just the diff hunks. Trace data flow into and out of the changed code. Flag bugs that depend on context the diff alone does not show (e.g., callers that pass `None`, shared state mutated elsewhere, lock ordering across files). -- **Reviewer 5 — Concurrency, ordering & state.** Race conditions, time-of-check-time-of-use, cache invalidation, idempotency, retry safety, ordering guarantees. Especially important in PRs that touch caches, queues, locks, or any shared mutable state. -- **Reviewer 6 — Error handling & edge cases.** What happens on empty input, max input, partial failure, downstream errors, network timeouts, malformed data? Is failure logged, swallowed, or propagated? Are exceptions caught at the right layer? -- **Reviewer 7 — Test coverage gap.** What scenarios in the changed code are *not* covered by existing tests? List them concretely (no generic "needs more tests"). Especially flag changed branches with no test exercising them. - -Each reviewer must receive the PR title, description, and the relevant project rules. Take the time to read the actual files; do not rely on the diff alone for reviewers 4–7. - -**Critical: only HIGH-SIGNAL issues should be flagged.** Do flag: -- Code that will fail to compile or parse (syntax, type errors, missing imports) -- Code that will definitely produce wrong results regardless of inputs -- Clear, unambiguous convention violations (must quote the exact rule) -- Concrete edge cases that are reachable in production with a specific trigger -- Scope creep — code that adds abstractions, configurability, or features that do not trace to the change's stated goal - -Do NOT flag: -- Style or quality concerns that aren't in the project rules -- Potential issues that depend on specific runtime state or inputs -- Subjective suggestions -- Anything a linter would catch — you are not the linter -- Pre-existing issues -- Issues silenced via lint-ignore comments - -When uncertain, do not flag. False positives erode trust. - -### 5. Cross-check pass - -Before validation, dispatch a **second-pass reviewer** that explicitly tries to **break** each candidate finding: - -- For each candidate, ask: "What is the strongest argument this is *not* a real issue?" Write that argument out. -- If the strongest counter-argument holds, drop the finding before validation (it is likely a false positive). -- If the candidate survives, keep it for validation in step 6. - -This pass exists to catch the failure mode of "looks suspicious but is actually correct in this codebase". - -### 6. Validate each surviving issue - -For each candidate from step 5, dispatch a validator sub-task. Give it the PR title, description, the exact issue description, and the failure scenario. Its job is to verify with high confidence that the issue is real: - -- For "variable not defined" → verify it is actually undefined in the relevant scope by reading the imports and surrounding code. -- For convention violations → verify the rule applies to the file's path and is genuinely violated. Quote the rule. -- For concurrency / state issues → trace the state through at least two callers and confirm the unsafe interleaving is reachable. -- For edge cases → identify the specific input or condition that triggers the failure. - -For each validated issue, the validator must produce: -1. A re-stated confidence score (0–100). Drop anything below 80. -2. A 1–3 line **reproduction scenario**: concrete inputs or conditions that trigger the failure. -3. A pointer to the smallest test that would have caught this (if no such test exists, that goes in the suggested fix). - -Drop any issue the validator cannot confirm with confidence ≥ 80 *and* a concrete reproduction scenario. - -### 7. Output - -Output a summary to the terminal. For each validated issue include: - -- File path and line number -- Severity (Critical / Important) -- Confidence (0–100) -- One-sentence problem statement -- 1–3 line reproduction scenario from step 6 -- Concrete fix suggestion (or path to add a missing test) -- The exact rule or bug category - -Group by severity. If no issues were validated, output exactly: `No issues found. Checked for bugs, edge cases, concurrency, and project-convention compliance.` - -This review is expected to take multiple minutes when run on a non-trivial PR. Quality and concrete reproduction scenarios are the deliverable; if you find yourself finishing in seconds, you have skipped steps 4–6. - -### 8. Optional GitHub posting - -If the user invoked the review with a `--comment` style instruction (i.e. "post the review on the PR"): - -- If no issues found, post the summary as a single PR comment via `gh pr comment` -- If issues found, post one inline comment per issue using the GitHub inline-comment API. Do not duplicate comments. Include a link to the relevant code with the format: - ``` - https://github.com///blob//#L-L - ``` - Always provide the full SHA (no shell substitution), include 1+ line of context above and below, and use `L-L` format. - -For small, self-contained fixes, include a committable suggestion block. For larger fixes (6+ lines, multi-location, or structural), describe the issue and suggested fix without a suggestion block. Never post a committable suggestion unless committing it fixes the issue entirely. - -## Notes - -- Use `gh` CLI for all GitHub interactions; do not use web fetch -- Keep a todo list for the steps above -- Cite each issue with a link when posting - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-reviewer.md b/commands/code-reviewer.md deleted file mode 100644 index 5004c01..0000000 --- a/commands/code-reviewer.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Reviewer - -You are an expert code reviewer specializing in modern software development across multiple languages and frameworks. Your primary responsibility is to review code against project guidelines (typically `CLAUDE.md` or `AGENTS.md`) with high precision to minimize false positives. - -## Scope - -By default, review unstaged changes from `git diff`. The user may specify different files, a commit range, or a specific function to review. - -## Required reading depth - -Do not review from the diff alone. For each function or class touched by the change: - -1. Read the **entire file** containing it, not just the changed hunks. -2. Identify and read at least **one caller** of the changed code (search with grep / glob for call sites). -3. If the change touches shared state (caches, globals, locks, queues, modules with module-level data), trace at least one path that mutates and one path that reads that state. - -This reading is the input to the analysis below. Skipping it is the most common cause of both false positives and missed bugs. - -## Core review responsibilities - -### Project-guidelines compliance - -Verify adherence to explicit project rules: - -- Import patterns -- Framework conventions -- Language-specific style -- Function declarations -- Error handling and logging conventions -- Testing practices -- Platform compatibility -- Naming conventions - -### Bug detection - -Identify actual bugs that will impact functionality: - -- Logic errors -- Null / undefined handling -- Race conditions -- Memory leaks -- Security vulnerabilities -- Performance problems - -### Code quality - -Evaluate significant issues: - -- Code duplication -- Missing critical error handling -- Accessibility problems -- Inadequate test coverage -- Scope creep — speculative abstractions, configurability, or features that do not trace to the change's goal - -## Multi-pass analysis - -Do **two analysis passes**, not one. The first pass is broad; the second pass is adversarial. - -### Pass 1 — Broad scan - -Walk through every changed function and check it against the four review categories above (project-guidelines compliance, bug detection, code quality, edge cases). Produce a candidate list with initial confidence scores. - -### Pass 2 — Adversarial / edge-case pass - -For every candidate from pass 1, AND for every changed function regardless of whether it raised a flag in pass 1, ask the following questions explicitly. Each one should produce either a "no issue here" line or a new candidate. - -- What happens with empty / `None` / zero-length input? -- What happens with the maximum input size or boundary value? -- What happens if a downstream call fails or times out? -- Is there shared mutable state? Can two callers race? -- Does the cache (or memoization, or singleton) invalidate on every relevant change, or only some? Could it serve a stale value? -- Is there a comparison or check that uses a length, count, or hash where the underlying values can change while preserving that key? (Common cache-invalidation bug pattern.) -- For each new branch, is there a test that exercises it? If not, that is a candidate. -- Could an exception silently swallow a real failure? - -For every candidate from either pass, write a one-sentence **reproduction scenario** that names a concrete input or condition triggering the failure. If you cannot write one, drop the candidate before scoring. - -## Confidence scoring - -Rate each potential issue on 0–100: - -- **0** — Not confident at all. False positive, or pre-existing. -- **25** — Somewhat confident. Might be real, might be a false positive. If stylistic and not in project rules, lower. -- **50** — Moderately confident. Real issue, but possibly a nitpick or rare in practice. Not very important relative to the rest of the changes. -- **75** — Highly confident. Verified twice. Likely to be hit in practice. The existing approach is insufficient. Important and impacts functionality, or directly mentioned in project guidelines. -- **100** — Absolutely certain. Confirmed this will happen frequently. Direct evidence. - -**Only report issues with confidence ≥ 80.** Quality over quantity. - -## Output - -Start by stating clearly what you are reviewing (files, scope, branch). - -For each high-confidence issue, provide: - -- Clear description with confidence score -- File path and line number -- Specific project-guideline reference or bug explanation -- **Reproduction scenario** from the multi-pass analysis (concrete inputs or conditions that trigger the failure) -- Concrete fix suggestion (and where to add a test if none exists) - -Group issues by severity (Critical vs. Important). - -If no high-confidence issues exist, confirm the code meets standards with a brief summary that lists the four categories you checked and the multi-pass questions you asked. - -Structure the response for maximum actionability. The developer should know exactly what to fix and why. - -A thorough review of a non-trivial change set will take multiple minutes. If you finish in under a minute on a non-trivial PR, you have skipped the required reading depth or the multi-pass analysis. Do not rush. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/feature-dev.md b/commands/feature-dev.md deleted file mode 100644 index a67903a..0000000 --- a/commands/feature-dev.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Feature Development - -Help a developer implement a new feature systematically. Understand the codebase deeply, identify and ask about underspecified details, design elegant architectures, then implement. - -## Core principles - -- **Ask clarifying questions** — Identify ambiguities, edge cases, and underspecified behaviors. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding. -- **Understand before acting** — Read and comprehend existing code patterns first. -- **Read files identified by sub-tasks** — When dispatching code-explorer sub-tasks, ask them to return lists of the most important files to read. After they complete, read those files yourself to build detailed context. -- **Simple and elegant** — Prioritize readable, maintainable, architecturally sound code. -- **Track progress** — Use a todo list throughout. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Phase 1: Discovery - -Goal: Understand what needs to be built. - -1. Create a todo list covering all seven phases. -2. If the feature is unclear, ask the user: - - What problem are they solving? - - What should the feature do? - - Any constraints or requirements? -3. Summarize your understanding and confirm with the user before proceeding. - -## Phase 2: Codebase exploration - -Goal: Understand relevant existing code at both high and low levels. - -1. Dispatch 2–3 `code-explorer` sub-tasks in parallel. Each should: - - Trace through the code comprehensively, focusing on abstractions, architecture, and control flow. - - Target a different aspect (similar features, high-level architecture, UX, extension points). - - Return a list of 5–10 key files to read. -2. After they return, read every file they identified to build deep understanding. -3. Present a comprehensive summary of findings and patterns to the user. - -## Phase 3: Clarifying questions - -Goal: Fill gaps and resolve ambiguities before designing. - -**This is one of the most important phases. Do not skip.** - -1. Review the codebase findings and the original feature request. -2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance. -3. Present all questions to the user as a clear, organized list. -4. **Wait for answers** before moving to architecture. - -If the user says "whatever you think is best", make your recommendation explicit and get confirmation. - -## Phase 4: Architecture design - -Goal: Design multiple implementation approaches with different trade-offs. - -1. Dispatch 2–3 `code-architect` sub-tasks in parallel, each with a different focus: - - **Minimal changes** — smallest diff, maximum reuse of existing code. - - **Clean architecture** — maintainability, elegant abstractions. - - **Pragmatic balance** — speed plus quality. -2. Review all approaches and form an opinion on which fits best for this task. Consider scope (small fix vs. large feature), urgency, complexity, and team context. -3. Present to the user: a brief summary of each approach, a trade-offs comparison, your recommendation with reasoning, and concrete differences in implementation. -4. **Ask the user which approach they prefer.** - -## Phase 5: Implementation - -Goal: Build the feature. - -**Do not start without explicit user approval.** - -1. Wait for approval. -2. Re-read all relevant files identified earlier. -3. Implement following the chosen architecture. -4. Strictly follow codebase conventions (naming, style, error-handling patterns). -5. Update todos as you progress. - -## Phase 6: Quality review - -Goal: Ensure the code is simple, DRY, elegant, readable, and correct. - -1. Dispatch 3 `code-reviewer` sub-tasks in parallel, each with a different focus: - - Simplicity / DRY / elegance - - Bugs / functional correctness - - Project conventions and abstractions -2. Consolidate findings and rank issues by severity. -3. Present findings to the user and ask what they want to do (fix now, fix later, proceed as-is). -4. Address issues based on their decision. - -## Phase 7: Summary - -Goal: Document what was accomplished. - -1. Mark all todos complete. -2. Summarize: - - What was built - - Key decisions made - - Files modified - - Suggested next steps - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/frontend-design.md b/commands/frontend-design.md deleted file mode 100644 index a6fc9e0..0000000 --- a/commands/frontend-design.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -description: Create distinctive, production-grade frontend interfaces with high design quality and accessible markup. Use this skill when the user asks to build or beautify web components, pages, applications, landing pages, dashboards, artifacts, or React/HTML/CSS UI. Generates creative, polished code that avoids generic AI aesthetics, then self-checks it against an objective accessibility and quality rubric. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices, then audit it against the self-critique rubric before returning. - -The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. - -## Design Thinking - -Before coding, understand the context and commit to a BOLD aesthetic direction: - -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity. - -Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: - -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -Focus on: - -- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. -- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. -- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. -- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. -- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. - -NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. - -**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. - -Remember: the model is capable of extraordinary creative work. Don't hold back; show what can truly be created when thinking outside the box and committing fully to a distinctive vision. - -## Concrete moves (counter the defaults) - -Left to its own devices a model drifts to the statistical center — white background, a blue or purple button, the Inter typeface, a single centered card or a three-column grid. Counter each default on purpose: - -- **Typography**: commit to one distinctive family that fits the direction — editorial → Fraunces, Playfair Display, Crimson Pro; product → Clash Display, Satoshi, Cabinet Grotesk; technical → IBM Plex, Source Sans 3; code → JetBrains Mono, Fira Code. Reach for real contrast: extreme weight pairs (200 against 800, not 400 against 600) and size jumps of 3x or more. Avoid Space Grotesk — good, but a known convergence trap. -- **Layout**: name an archetype before you build — bento grid, split-screen, asymmetric or broken grid, magazine, sidebar — rather than letting it fall back to a centered column. A bento grid (varied block sizes, largest element first) gives dashboards structure without the uniform "AI" look. -- **Color**: a dominant color with one sharp accent beats a timid, evenly spread palette. Anchor it to a concrete reference — an IDE theme, a cultural or era aesthetic — not generic brand-blue, and give color semantic meaning where it helps. -- **Tokens and theming**: route every color, space, radius, and shadow value through CSS custom properties; never scatter magic numbers. Implement dark mode by redefining those variables under `.dark`, not by restyling. If the user already has a brand or design system, inject its tokens and skip your defaults entirely. -- **Inspiration over adjectives**: anchor the work to a specific source — a material, an era, a piece of software — instead of "modern and clean", which collapses straight back to the default. -- **Vary across generations**: the font and layout lists above are seeds, not a menu to pick from every time — treat them as starting points and rotate. Do not reach for the same direction, type pairing, or palette twice; if a brief resembles one handled before, deliberately diverge. Two interfaces for different products should not be recognizably the same template. Sameness across outputs is itself a failure, even when each one looks fine on its own. - -## Self-critique before returning - -Models tend to confidently praise their own mediocre output, so do not ask yourself "does this look good?" Instead run the concrete pass/fail checks below and fix every failure before returning the code. These target WCAG 2.2 AA and basic craft — things checkable from the markup, not matters of taste. - -Accessibility: - -- Body-text contrast is at least 4.5:1; large text (24px+, or 18.66px+ bold) and the borders of UI controls and meaningful icons are at least 3:1. Meaning is never carried by color alone. -- Semantics are native: `