diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..8607af9 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,380 @@ +{ + "name": "awesome-codex-plugins", + "interface": { + "displayName": "Awesome Codex Plugins" + }, + "plugins": [ + { + "name": "registry-broker-codex-plugin", + "source": { + "source": "local", + "path": "./plugins/hashgraph-online/registry-broker-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "agentops", + "source": { + "source": "local", + "path": "./plugins/boshu2/agentops" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "bp", + "source": { + "source": "local", + "path": "./plugins/JuliusBrussee/blueprint" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "brooks-lint", + "source": { + "source": "local", + "path": "./plugins/hyhmrright/brooks-lint" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "claude-code-skills", + "source": { + "source": "local", + "path": "./plugins/alirezarezvani/claude-skills" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "claude-octopus", + "source": { + "source": "local", + "path": "./plugins/nyldn/claude-octopus" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "ateam", + "source": { + "source": "local", + "path": "./plugins/yimwoo/codex-agenteam" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "codex-multi-auth", + "source": { + "source": "local", + "path": "./plugins/ndycode/codex-multi-auth" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "codex-reviewer", + "source": { + "source": "local", + "path": "./plugins/schuettc/codex-reviewer" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "hotl", + "source": { + "source": "local", + "path": "./plugins/yimwoo/hotl-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "codex-project-autopilot", + "source": { + "source": "local", + "path": "./plugins/AlexMi64/codex-project-autopilot" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow" + }, + { + "name": "amq-cli", + "source": { + "source": "local", + "path": "./plugins/avivsinai/agent-message-queue" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "apple-calendar", + "source": { + "source": "local", + "path": "./plugins/matk0shub/apple-productivity-mcp" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "bkt", + "source": { + "source": "local", + "path": "./plugins/avivsinai/bitbucket-cli" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "chrome-devtools", + "source": { + "source": "local", + "path": "./plugins/win4r/chrome-devtools-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "be-serious", + "source": { + "source": "local", + "path": "./plugins/lulucatdev/codex-be-serious" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "codex-mem", + "source": { + "source": "local", + "path": "./plugins/2kDarki/codex-mem" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "context-pack", + "source": { + "source": "local", + "path": "./plugins/Rothschildiuk/context-pack" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "jk", + "source": { + "source": "local", + "path": "./plugins/avivsinai/jenkins-cli" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "kicad-happy", + "source": { + "source": "local", + "path": "./plugins/aklofas/kicad-happy" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "langfuse", + "source": { + "source": "local", + "path": "./plugins/avivsinai/langfuse-mcp" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "launchfast", + "source": { + "source": "local", + "path": "./plugins/BlockchainHB/launchfast_codex_plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "oc-chatgpt-multi-auth", + "source": { + "source": "local", + "path": "./plugins/ndycode/oc-chatgpt-multi-auth" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "openproject", + "source": { + "source": "local", + "path": "./plugins/varaprasadreddy9676/team-codex-plugins" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "orgx-codex-plugin", + "source": { + "source": "local", + "path": "./plugins/useorgx/orgx-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "panews", + "source": { + "source": "local", + "path": "./plugins/panewslab/skills" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "papersflow-codex-plugin", + "source": { + "source": "local", + "path": "./plugins/papersflow-ai/papersflow-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "ru-text", + "source": { + "source": "local", + "path": "./plugins/talkstream/ru-text" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "task-scheduler", + "source": { + "source": "local", + "path": "./plugins/6Delta9/task-scheduler-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "tokrepo-search", + "source": { + "source": "local", + "path": "./plugins/henu-wang/tokrepo-codex-plugin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + }, + { + "name": "yandex-direct-for-all", + "source": { + "source": "local", + "path": "./plugins/nebelov/yandex-direct-for-all" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations" + } + ] +} diff --git a/.github/workflows/validate-plugins.yml b/.github/workflows/validate-plugins.yml index 409858b..67bd8c6 100644 --- a/.github/workflows/validate-plugins.yml +++ b/.github/workflows/validate-plugins.yml @@ -1,16 +1,20 @@ -name: Sync plugins.json +name: Sync marketplace artifacts on: pull_request: paths: - README.md - plugins.json + - .agents/plugins/marketplace.json + - plugins/** - scripts/generate_plugins_json.py push: branches: [main] paths: - README.md - plugins.json + - .agents/plugins/marketplace.json + - plugins/** - scripts/generate_plugins_json.py permissions: @@ -18,7 +22,7 @@ permissions: jobs: sync: - name: Sync plugins.json with README + name: Sync marketplace artifacts with README runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -30,13 +34,13 @@ jobs: - name: Regenerate and commit if changed run: | python3 scripts/generate_plugins_json.py - if ! git diff --quiet plugins.json; then - echo "::notice::plugins.json was out of sync โ€” auto-committing" + if ! git diff --quiet -- plugins.json .agents/plugins/marketplace.json plugins; then + echo "::notice::marketplace artifacts were out of sync โ€” auto-committing" git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add plugins.json - git commit -m "chore: sync plugins.json with README" + git add plugins.json .agents/plugins/marketplace.json plugins + git commit -m "chore: sync marketplace artifacts with README" git push else - echo "plugins.json is up to date" + echo "marketplace artifacts are up to date" fi diff --git a/README.md b/README.md index f3acc0a..bc626aa 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,8 @@ pipx run codex-plugin-scanner lint . pipx run codex-plugin-scanner verify . ``` +This repo also publishes a real Codex repo marketplace at `.agents/plugins/marketplace.json`. The generated marketplace points at mirrored installable plugin bundles under `./plugins/`, so a local clone of this repository can act as a curated plugin source in Codex exactly the way the OpenAI docs describe. + ## Official Plugins
@@ -145,6 +147,8 @@ $plugin-creator Currently no self-serve marketplace submission. Plugins are distributed via local marketplaces (`~/.agents/plugins/marketplace.json`), repo marketplaces (`$REPO_ROOT/.agents/plugins/marketplace.json`), or GitHub repos by pointing a marketplace source at a repo. OpenAI has stated third-party marketplace submissions are coming soon. +For this curated list, the machine-readable source of truth is the generated repo marketplace at `.agents/plugins/marketplace.json`. We keep the README for humans and `plugins.json` as a compatibility export for existing automation. + ## Validate Before You Ship After scaffolding with `$plugin-creator`, use [codex-plugin-scanner](https://github.com/hashgraph-online/codex-plugin-scanner) as your quality gate before publishing, review, or distribution. diff --git a/plugins/2kDarki/codex-mem/.codex-plugin/plugin.json b/plugins/2kDarki/codex-mem/.codex-plugin/plugin.json new file mode 100644 index 0000000..92abbb0 --- /dev/null +++ b/plugins/2kDarki/codex-mem/.codex-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "codex-mem", + "version": "10.6.2", + "description": "Persistent memory system for Codex - seamlessly preserve context across sessions", + "author": { + "name": "Alex Newman" + }, + "repository": "https://github.com/thedotmack/claude-mem", + "license": "AGPL-3.0", + "keywords": [ + "memory", + "context", + "persistence", + "hooks", + "mcp" + ] +} diff --git a/plugins/2kDarki/codex-mem/LICENSE b/plugins/2kDarki/codex-mem/LICENSE new file mode 100644 index 0000000..5bb20ff --- /dev/null +++ b/plugins/2kDarki/codex-mem/LICENSE @@ -0,0 +1,630 @@ + GNU AFFERO GENERAL PUBLIC LICENSE + Version 3, 19 November 2007 + + Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved. + + This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + + This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License +along with this program. If not, see . + + Preamble + + The GNU Affero General Public License is a free, copyleft license for +software and other kinds of works, specifically designed to ensure +cooperation with the community in the case of network server software. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +our General Public Licenses are intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + Developers that use our General Public Licenses protect your rights +with two steps: (1) assert copyright on the software, and (2) offer +you this License which gives you legal permission to copy, distribute +and/or modify the software. + + A secondary benefit of defending all users' freedom is that +improvements made in alternate versions of the program, if they +receive widespread use, become available for other developers to +incorporate. Many developers of free software are heartened and +encouraged by the resulting cooperation. However, in the case of +software used on network servers, this result may fail to come about. +The GNU General Public License permits making a modified version and +letting the public access it on a server without ever releasing its +source code to the public. + + The GNU Affero General Public License is designed specifically to +ensure that, in such cases, the modified source code becomes available +to the community. It requires the operator of a network server to +provide the source code of the modified version running there to the +users of that server. Therefore, public use of a modified version, on +a publicly accessible server, gives the public access to the source +code of the modified version. + + An older license, called the Affero General Public License and +published by Affero, was designed to accomplish similar goals. This is +a different license, not a version of the Affero GPL, but Affero has +released a new version of the Affero GPL which permits relicensing under +this license. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU Affero General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Remote Network Interaction; Use with the GNU General Public License. + + Notwithstanding any other provision of this License, if you modify the +Program, your modified version must prominently offer all users +interacting with it remotely through a computer network (if your version +supports such interaction) an opportunity to receive the Corresponding +Source of your version by providing access to the Corresponding Source +from a network server at no charge, through some standard or customary +means of facilitating copying of software. This Corresponding Source +shall include the Corresponding Source for any work covered by version 3 +of the GNU General Public License that is incorporated pursuant to the +following paragraph. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the work with which it is combined will remain governed by version +3 of the GNU General Public License. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU Affero General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU Affero General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU Affero General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU Affero General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS \ No newline at end of file diff --git a/plugins/2kDarki/codex-mem/README.md b/plugins/2kDarki/codex-mem/README.md new file mode 100644 index 0000000..c5b5070 --- /dev/null +++ b/plugins/2kDarki/codex-mem/README.md @@ -0,0 +1,365 @@ +

+
+ + + + + Codex-mem + + +
+

+ +

+ ๐Ÿ‡จ๐Ÿ‡ณ ไธญๆ–‡ โ€ข + ๐Ÿ‡น๐Ÿ‡ผ ็น้ซ”ไธญๆ–‡ โ€ข + ๐Ÿ‡ฏ๐Ÿ‡ต ๆ—ฅๆœฌ่ชž โ€ข + ๐Ÿ‡ต๐Ÿ‡น Portuguรชs โ€ข + ๐Ÿ‡ง๐Ÿ‡ท Portuguรชs โ€ข + ๐Ÿ‡ฐ๐Ÿ‡ท ํ•œ๊ตญ์–ด โ€ข + ๐Ÿ‡ช๐Ÿ‡ธ Espaรฑol โ€ข + ๐Ÿ‡ฉ๐Ÿ‡ช Deutsch โ€ข + ๐Ÿ‡ซ๐Ÿ‡ท Franรงais โ€ข + ๐Ÿ‡ฎ๐Ÿ‡ฑ ืขื‘ืจื™ืช โ€ข + ๐Ÿ‡ธ๐Ÿ‡ฆ ุงู„ุนุฑุจูŠุฉ โ€ข + ๐Ÿ‡ท๐Ÿ‡บ ะ ัƒััะบะธะน โ€ข + ๐Ÿ‡ต๐Ÿ‡ฑ Polski โ€ข + ๐Ÿ‡จ๐Ÿ‡ฟ ฤŒeลกtina โ€ข + ๐Ÿ‡ณ๐Ÿ‡ฑ Nederlands โ€ข + ๐Ÿ‡น๐Ÿ‡ท Tรผrkรงe โ€ข + ๐Ÿ‡บ๐Ÿ‡ฆ ะฃะบั€ะฐั—ะฝััŒะบะฐ โ€ข + ๐Ÿ‡ป๐Ÿ‡ณ Tiแบฟng Viแป‡t โ€ข + ๐Ÿ‡ต๐Ÿ‡ญ Tagalog โ€ข + ๐Ÿ‡ฎ๐Ÿ‡ฉ Indonesia โ€ข + ๐Ÿ‡น๐Ÿ‡ญ เน„เธ—เธข โ€ข + ๐Ÿ‡ฎ๐Ÿ‡ณ เคนเคฟเคจเฅเคฆเฅ€ โ€ข + ๐Ÿ‡ง๐Ÿ‡ฉ เฆฌเฆพเฆ‚เฆฒเฆพ โ€ข + ๐Ÿ‡ต๐Ÿ‡ฐ ุงุฑุฏูˆ โ€ข + ๐Ÿ‡ท๐Ÿ‡ด Romรขnฤƒ โ€ข + ๐Ÿ‡ธ๐Ÿ‡ช Svenska โ€ข + ๐Ÿ‡ฎ๐Ÿ‡น Italiano โ€ข + ๐Ÿ‡ฌ๐Ÿ‡ท ฮ•ฮปฮปฮทฮฝฮนฮบฮฌ โ€ข + ๐Ÿ‡ญ๐Ÿ‡บ Magyar โ€ข + ๐Ÿ‡ซ๐Ÿ‡ฎ Suomi โ€ข + ๐Ÿ‡ฉ๐Ÿ‡ฐ Dansk โ€ข + ๐Ÿ‡ณ๐Ÿ‡ด Norsk +

+ +

Persistent memory compression system built for Codex.

+ +

+ + License + + + Version + + + Node + + + Mentioned in Awesome Claude Code + +

+ +

+ + + + + thedotmack/claude-mem | Trendshift + + +

+ +
+ + + + + + +
+ + + Codex-mem Preview + + + + + + + + Star History Chart + + +
+ +

+ Quick Start โ€ข + How It Works โ€ข + Search Tools โ€ข + Documentation โ€ข + Configuration โ€ข + Troubleshooting โ€ข + License +

+ +

+ Codex-mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Codex to maintain continuity of knowledge about projects even after sessions end or reconnect. +

+ +--- + +## Quick Start + +Install codex-mem globally and set up Codex transcript watching: + +```bash +npm install -g @2kdarki/codex-mem +codex-mem codex init +codex-mem codex watch +``` + +Start or resume a Codex session after the watcher is running and context from previous sessions will appear automatically. + +> **Compatibility note:** Codex is the primary runtime and product surface. Claude Code and Cursor remain supported compatibility hosts on the same worker, database, and search pipeline. + +### ๐Ÿฆž OpenClaw Gateway + +Install codex-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command: + +```bash +curl -fsSL https://install.cmem.ai/openclaw.sh | bash +``` + +The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.codex-mem.ai/openclaw-integration) for details. + +**Key Features:** + +- ๐Ÿง  **Persistent Memory** - Context survives across sessions +- ๐Ÿ“Š **Progressive Disclosure** - Layered memory retrieval with token cost visibility +- ๐Ÿ” **Skill-Based Search** - Query your project history with mem-search skill +- ๐Ÿ–ฅ๏ธ **Web Viewer UI** - Real-time memory stream at http://localhost:37777 +- ๐Ÿ’ป **Desktop Skill** - Search memory from desktop conversations +- ๐Ÿ”’ **Privacy Control** - Use `` tags to exclude sensitive content from storage +- โš™๏ธ **Context Configuration** - Fine-grained control over what context gets injected +- ๐Ÿค– **Automatic Operation** - No manual intervention required +- ๐Ÿ”— **Citations** - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777) +- ๐Ÿงช **Beta Channel** - Try experimental features like Endless Mode via version switching + +--- + +## Documentation + +๐Ÿ“š **[View Full Documentation](https://docs.codex-mem.ai/)** - Browse on official website + +### Getting Started + +- **[Installation Guide](https://docs.codex-mem.ai/installation)** - Quick start & advanced installation +- **[Usage Guide](https://docs.codex-mem.ai/usage/getting-started)** - How codex-mem works automatically +- **[Search Tools](https://docs.codex-mem.ai/usage/search-tools)** - Query your project history with natural language +- **[Beta Features](https://docs.codex-mem.ai/beta-features)** - Try experimental features like Endless Mode + +### Best Practices + +- **[Context Engineering](https://docs.codex-mem.ai/context-engineering)** - AI agent context optimization principles +- **[Progressive Disclosure](https://docs.codex-mem.ai/progressive-disclosure)** - Philosophy behind codex-mem's context priming strategy + +### Architecture + +- **[Overview](https://docs.codex-mem.ai/architecture/overview)** - System components & data flow +- **[Architecture Evolution](https://docs.codex-mem.ai/architecture-evolution)** - The journey from v3 to v5 +- **[Hooks Architecture](https://docs.codex-mem.ai/hooks-architecture)** - How codex-mem uses lifecycle hooks +- **[Hooks Reference](https://docs.codex-mem.ai/architecture/hooks)** - 7 hook scripts explained +- **[Worker Service](https://docs.codex-mem.ai/architecture/worker-service)** - HTTP API & Bun management +- **[Database](https://docs.codex-mem.ai/architecture/database)** - SQLite schema & FTS5 search +- **[Search Architecture](https://docs.codex-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database + +### Configuration & Development + +- **[Configuration](https://docs.codex-mem.ai/configuration)** - Environment variables & settings +- **[Development](https://docs.codex-mem.ai/development)** - Building, testing, contributing +- **[Troubleshooting](https://docs.codex-mem.ai/troubleshooting)** - Common issues & solutions + +--- + +## How It Works + +**Core Components:** + +1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts) +2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook) +3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun +4. **SQLite Database** - Stores sessions, observations, summaries +5. **mem-search Skill** - Natural language queries with progressive disclosure +6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval + +See [Architecture Overview](https://docs.codex-mem.ai/architecture/overview) for details. + +--- + +## MCP Search Tools + +Codex-mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**: + +**The 3-Layer Workflow:** + +1. **`search`** - Get compact index with IDs (~50-100 tokens/result) +2. **`timeline`** - Get chronological context around interesting results +3. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result) + +**How It Works:** +- Codex uses MCP tools to search your memory +- Start with `search` to get an index of results +- Use `timeline` to see what was happening around specific observations +- Use `get_observations` to fetch full details for relevant IDs +- **~10x token savings** by filtering before fetching details + +**Available MCP Tools:** + +1. **`search`** - Search memory index with full-text queries, filters by type/date/project +2. **`timeline`** - Get chronological context around a specific observation or query +3. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs) + +**Example Usage:** + +```typescript +// Step 1: Search for index +search(query="authentication bug", type="bugfix", limit=10) + +// Step 2: Review index, identify relevant IDs (e.g., #123, #456) + +// Step 3: Fetch full details +get_observations(ids=[123, 456]) +``` + +See [Search Tools Guide](https://docs.codex-mem.ai/usage/search-tools) for detailed examples. + +--- + +## Beta Features + +Codex-mem offers a **beta channel** with experimental features like **Endless Mode** (biomimetic memory architecture for extended sessions). Switch between stable and beta versions from the web viewer UI at http://localhost:37777 โ†’ Settings. + +See **[Beta Features Documentation](https://docs.codex-mem.ai/beta-features)** for details on Endless Mode and how to try it. + +--- + +## System Requirements + +- **Node.js**: 18.0.0 or higher +- **Codex**: Latest version with local session history enabled +- **Bun**: JavaScript runtime and process manager (auto-installed if missing) +- **uv**: Python package manager for vector search (auto-installed if missing) +- **SQLite 3**: For persistent storage (bundled) + +--- +### Windows Setup Notes + +If you see an error like: + +```powershell +npm : The term 'npm' is not recognized as the name of a cmdlet +``` + +Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation. + +--- + +## Configuration + +Settings are managed in `~/.Codex-mem/settings.json` (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings. + +See the **[Configuration Guide](https://docs.codex-mem.ai/configuration)** for all available settings and examples. + +--- + +## Development + +See the **[Development Guide](https://docs.codex-mem.ai/development)** for build instructions, testing, and contribution workflow. + +--- + +## Troubleshooting + +If experiencing issues, describe the problem to Codex and the troubleshoot skill will automatically diagnose and provide fixes. + +See the **[Troubleshooting Guide](https://docs.codex-mem.ai/troubleshooting)** for common issues and solutions. + +--- + +## Bug Reports + +Create comprehensive bug reports with the automated generator: + +```bash +cd ~/.Codex/plugins/marketplaces/thedotmack +npm run bug-report +``` + +## Contributing + +Contributions are welcome! Please: + +1. Fork the repository +2. Create a feature branch +3. Make your changes with tests +4. Update documentation +5. Submit a Pull Request + +See [Development Guide](https://docs.codex-mem.ai/development) for contribution workflow. + +--- + +## License + +This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0). + +Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved. + +See the [LICENSE](LICENSE) file for full details. + +**What This Means:** + +- You can use, modify, and distribute this software freely +- If you modify and deploy on a network server, you must make your source code available +- Derivative works must also be licensed under AGPL-3.0 +- There is NO WARRANTY for this software + +**Note on Ragtime**: The `ragtime/` directory is licensed separately under the **PolyForm Noncommercial License 1.0.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details. + +--- + +## Support + +- **Documentation**: [docs/](docs/) +- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues) +- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) +- **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory) +- **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu) +- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack)) + +--- + +**Built with Claude Agent SDK** | **Powered by Codex** | **Made with TypeScript** + +--- + +### What About $CMEM? + +$CMEM is a solana token created by a 3rd party without Codex-mem's prior consent, but officially embraced by the creator of Codex-mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS diff --git a/plugins/2kDarki/codex-mem/package.json b/plugins/2kDarki/codex-mem/package.json new file mode 100644 index 0000000..afc9177 --- /dev/null +++ b/plugins/2kDarki/codex-mem/package.json @@ -0,0 +1,142 @@ +{ + "name": "@2kdarki/codex-mem", + "version": "10.6.2", + "description": "Persistent memory for Codex - persist context across sessions", + "keywords": [ + "codex", + "codex-cli", + "openai", + "mcp", + "plugin", + "memory", + "compression", + "knowledge-graph", + "transcript", + "typescript", + "nodejs" + ], + "author": "Alex Newman", + "license": "AGPL-3.0", + "repository": { + "type": "git", + "url": "https://github.com/2kDarki/codex-mem.git" + }, + "homepage": "https://github.com/2kDarki/codex-mem#readme", + "bugs": { + "url": "https://github.com/2kDarki/codex-mem/issues" + }, + "type": "module", + "bin": { + "codex-mem": "./plugin/scripts/codex-mem.cjs" + }, + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./sdk": { + "types": "./dist/sdk/index.d.ts", + "import": "./dist/sdk/index.js" + }, + "./modes/*": "./plugin/modes/*" + }, + "files": [ + "dist", + "plugin" + ], + "engines": { + "node": ">=18.0.0", + "bun": ">=1.0.0" + }, + "scripts": { + "dev": "npm run build-and-sync", + "build": "node scripts/build-hooks.js", + "build-and-sync": "npm run build && npm run sync-marketplace && sleep 1 && cd ~/.Codex/plugins/marketplaces/thedotmack && npm run worker:restart", + "sync-marketplace": "node scripts/sync-marketplace.cjs", + "sync-marketplace:force": "node scripts/sync-marketplace.cjs --force", + "build:binaries": "node scripts/build-worker-binary.js", + "worker:logs": "tail -n 50 ~/.Codex-mem/logs/worker-$(date +%Y-%m-%d).log", + "worker:tail": "tail -f 50 ~/.Codex-mem/logs/worker-$(date +%Y-%m-%d).log", + "changelog:generate": "node scripts/generate-changelog.js", + "discord:notify": "node scripts/discord-release-notify.js", + "codex:init": "node plugin/scripts/codex-mem.cjs codex init", + "codex:watch": "node plugin/scripts/codex-mem.cjs codex watch", + "codex:validate": "node plugin/scripts/codex-mem.cjs codex validate", + "worker:start": "bun plugin/scripts/worker-service.cjs start", + "worker:stop": "bun plugin/scripts/worker-service.cjs stop", + "worker:restart": "bun plugin/scripts/worker-service.cjs restart", + "worker:status": "bun plugin/scripts/worker-service.cjs status", + "queue": "bun scripts/check-pending-queue.ts", + "queue:process": "bun scripts/check-pending-queue.ts --process", + "queue:clear": "bun scripts/clear-failed-queue.ts --all --force", + "agents-md:regenerate": "bun scripts/regenerate-agents-md.ts", + "agents-md:dry-run": "bun scripts/regenerate-agents-md.ts --dry-run", + "translate-readme": "bun scripts/translate-readme/cli.ts -v -o docs/i18n README.md", + "translate:tier1": "npm run translate-readme -- zh zh-tw ja pt-br ko es de fr", + "translate:tier2": "npm run translate-readme -- he ar ru pl cs nl tr uk", + "translate:tier3": "npm run translate-readme -- vi id th hi bn ro sv", + "translate:tier4": "npm run translate-readme -- it el hu fi da no", + "translate:all": "npm run translate:tier1 & npm run translate:tier2 & npm run translate:tier3 & npm run translate:tier4 & wait", + "bug-report": "npx tsx scripts/bug-report/cli.ts", + "cursor:install": "bun plugin/scripts/worker-service.cjs cursor install", + "cursor:uninstall": "bun plugin/scripts/worker-service.cjs cursor uninstall", + "cursor:status": "bun plugin/scripts/worker-service.cjs cursor status", + "cursor:setup": "bun plugin/scripts/worker-service.cjs cursor setup", + "test": "bun test", + "test:sqlite": "bun test tests/sqlite/", + "test:agents": "bun test tests/worker/agents/", + "test:search": "bun test tests/worker/search/", + "test:context": "bun test tests/context/", + "test:infra": "bun test tests/infrastructure/", + "test:server": "bun test tests/server/", + "prepublishOnly": "npm run build", + "release": "np", + "release:patch": "np patch --no-cleanup", + "release:minor": "np minor --no-cleanup", + "release:major": "np major --no-cleanup" + }, + "np": { + "yarn": false, + "contents": ".", + "testScript": "test", + "2fa": false + }, + "dependencies": { + "@anthropic-ai/claude-agent-sdk": "^0.1.76", + "@modelcontextprotocol/sdk": "^1.25.1", + "ansi-to-html": "^0.7.2", + "dompurify": "^3.3.1", + "express": "^4.18.2", + "glob": "^11.0.3", + "handlebars": "^4.7.8", + "react": "^18.3.1", + "react-dom": "^18.3.1", + "yaml": "^2.8.2", + "zod-to-json-schema": "^3.24.6" + }, + "devDependencies": { + "@types/cors": "^2.8.19", + "@types/dompurify": "^3.0.5", + "@types/express": "^4.17.21", + "@types/node": "^20.0.0", + "@types/react": "^18.3.5", + "@types/react-dom": "^18.3.0", + "esbuild": "^0.27.2", + "np": "^11.0.2", + "tree-sitter-c": "^0.24.1", + "tree-sitter-cli": "^0.26.5", + "tree-sitter-cpp": "^0.23.4", + "tree-sitter-go": "^0.25.0", + "tree-sitter-java": "^0.23.5", + "tree-sitter-javascript": "^0.25.0", + "tree-sitter-python": "^0.25.0", + "tree-sitter-ruby": "^0.23.1", + "tree-sitter-rust": "^0.24.0", + "tree-sitter-typescript": "^0.23.2", + "tsx": "^4.20.6", + "typescript": "^5.3.0" + }, + "optionalDependencies": { + "tree-kill": "^1.2.2" + } +} diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/.codex-plugin/plugin.json b/plugins/6Delta9/task-scheduler-codex-plugin/.codex-plugin/plugin.json new file mode 100644 index 0000000..6fac612 --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/.codex-plugin/plugin.json @@ -0,0 +1,52 @@ +{ + "name": "task-scheduler", + "version": "0.2.0", + "description": "Turn deadlines, workload, and blockers into a realistic task schedule.", + "author": { + "name": "zeyad elsharkawy", + "email": "opensource@6delta9.dev", + "url": "https://github.com/6Delta9" + }, + "homepage": "https://github.com/6Delta9/task-scheduler-codex-plugin", + "repository": "https://github.com/6Delta9/task-scheduler-codex-plugin", + "license": "MIT", + "keywords": [ + "tasks", + "scheduler", + "planning", + "productivity" + ], + "skills": "./skills/", + "hooks": "./hooks.json", + "mcpServers": "./.mcp.json", + "apps": "./.app.json", + "interface": { + "displayName": "Task Scheduler", + "shortDescription": "Build realistic schedules from tasks, deadlines, and capacity.", + "longDescription": "Task Scheduler turns raw tasks into a day-by-day plan with workload balancing, blocked dates, overflow tracking, and reusable MCP tools.", + "developerName": "zeyad elsharkawy", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write", + "Automation", + "Planning" + ], + "websiteURL": "https://github.com/6Delta9/task-scheduler-codex-plugin", + "privacyPolicyURL": "https://github.com/6Delta9/task-scheduler-codex-plugin/blob/main/PRIVACY.md", + "termsOfServiceURL": "https://github.com/6Delta9/task-scheduler-codex-plugin/blob/main/TERMS.md", + "defaultPrompt": [ + "Use Task Scheduler to plan my week around deadlines and blocked days.", + "Use Task Scheduler to turn this task list into a realistic schedule.", + "Use Task Scheduler to spot overflow and capacity risks in this plan." + ], + "brandColor": "#0F766E", + "composerIcon": "./assets/icon.png", + "logo": "./assets/logo.png", + "screenshots": [ + "./assets/screenshot1.png", + "./assets/screenshot2.png", + "./assets/screenshot3.png" + ] + } +} diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/.codexignore b/plugins/6Delta9/task-scheduler-codex-plugin/.codexignore new file mode 100644 index 0000000..4072dcb --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/.codexignore @@ -0,0 +1,18 @@ +# Local caches and build artifacts +__pycache__/ +*.pyc +*.pyo +*.pyd + +# Python tooling caches +.pytest_cache/ +.mypy_cache/ + +# Local generated outputs +schedule.md + +# VCS and editor metadata +.git/ +.github/ +.DS_Store +Thumbs.db diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/LICENSE b/plugins/6Delta9/task-scheduler-codex-plugin/LICENSE new file mode 100644 index 0000000..1fa1c3e --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 zizo + +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/plugins/6Delta9/task-scheduler-codex-plugin/README.md b/plugins/6Delta9/task-scheduler-codex-plugin/README.md new file mode 100644 index 0000000..7ab9674 --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/README.md @@ -0,0 +1,298 @@ +# Task Scheduler for OpenAI Codex + +Task Scheduler is an OpenAI Codex plugin that turns raw task lists into realistic schedules. + +It combines three pieces in one plugin package: + +- a Codex plugin manifest and marketplace-ready metadata +- a reusable MCP server that other agents and tools can call +- a local CLI for generating schedule drafts from structured JSON input + +The plugin is designed for practical planning. It balances deadlines, available hours, blocked dates, and per-day capacity changes, then returns a markdown plan with follow-ups and risks. + +![Task Scheduler logo](./assets/logo.png) + +## Highlights + +- Converts task JSON into a day-by-day schedule +- Supports blocked dates and daily capacity overrides +- Tracks overflow when tasks do not fit inside the planning window +- Exposes MCP tools so other agents can call the scheduler directly +- Includes a Codex skill for planning-oriented prompts +- Ships with example assets, sample data, and starter plugin metadata + +## Who This Is For + +- Codex users who want a local productivity plugin +- plugin authors learning how to combine plugin manifests, skills, and MCP +- teams that want a lightweight planning tool agents can call from the same workspace + +## Repository Layout + +```text +task-scheduler/ +|-- .codex-plugin/ +| `-- plugin.json +|-- assets/ +| |-- icon.png +| |-- logo.png +| `-- screenshot*.png +|-- hooks/ +| `-- README.md +|-- scripts/ +| |-- build_schedule.py +| |-- example_tasks.json +| |-- mcp_server.py +| |-- requirements-mcp.txt +| `-- task_scheduler_core.py +|-- skills/ +| `-- task-planner/ +| `-- SKILL.md +|-- .app.json +|-- .mcp.json +|-- hooks.json +`-- README.md +``` + +## Features + +### 1. Local CLI scheduling + +Use the CLI when you want a quick schedule from a JSON file: + +```powershell +python .\scripts\build_schedule.py ` + --input .\scripts\example_tasks.json +``` + +Optional flags: + +- `--start-date YYYY-MM-DD` +- `--days ` +- `--hours-per-day ` +- `--output ` + +These flags override the values inside the JSON input file when present. + +### 2. MCP tools for agent workflows + +The plugin exposes a local stdio MCP server so other agents and tools can call the scheduler without shelling out directly. + +Implemented MCP tools: + +- `build_task_schedule` +- `analyze_schedule_capacity` +- `build_task_schedule_from_file` + +Implemented MCP resources: + +- `task-scheduler://sample-input` +- `task-scheduler://readme` + +Implemented MCP prompt: + +- `schedule_prompt` + +### 3. Codex skill support + +The included skill at `skills/task-planner/SKILL.md` helps Codex gather constraints, create a realistic plan, and call out risk and overflow clearly. + +## Input Format + +The scheduler accepts either: + +- a plain JSON array of tasks +- a JSON object containing `tasks` plus planning metadata + +### Minimal input + +```json +[ + { + "title": "Finalize project brief", + "due": "2026-04-03", + "estimated_hours": 2.5, + "priority": 5, + "notes": "Needs stakeholder review" + } +] +``` + +### Full input + +```json +{ + "start_date": "2026-04-01", + "days": 6, + "hours_per_day": 6, + "blocked_dates": ["2026-04-04"], + "daily_capacity_overrides": { + "2026-04-03": 3.5, + "2026-04-06": 4 + }, + "notes": "Protect Saturday for admin catch-up.", + "tasks": [ + { + "title": "Finalize project brief", + "due": "2026-04-02", + "estimated_hours": 2, + "priority": 5, + "tags": ["strategy", "stakeholders"], + "notes": "Share with stakeholders before noon." + } + ] +} +``` + +### Supported task fields + +- `title`: task name +- `due`: due date in `YYYY-MM-DD` +- `estimated_hours`: expected work in hours +- `priority`: integer from 1 to 5 +- `notes`: optional detail shown in output +- `tags`: optional string array for categorization + +### Supported schedule metadata + +- `start_date`: planning window start +- `days`: number of days in the window +- `hours_per_day`: default daily capacity +- `blocked_dates`: dates with zero scheduling capacity +- `daily_capacity_overrides`: per-day hour overrides +- `notes`: planning context echoed into the output + +## Example Output + +The generated markdown includes: + +- `Summary` +- `Schedule` +- `Follow-Ups` +- `Risks` + +This makes it readable for humans and easy for agents to refine. + +## Installation + +### 1. Clone or copy the repository + +This repository is structured with the plugin at the repo root. + +```text +task-scheduler-codex-plugin/ +``` + +To use it as a Codex plugin inside another workspace, place this repository or a copy of it under: + +```text +plugins/task-scheduler +``` + +### 2. Install the MCP dependency + +```powershell +python -m pip install -r .\scripts\requirements-mcp.txt +``` + +### 3. Verify the plugin manifest + +The manifest lives at: + +```text +.codex-plugin/plugin.json +``` + +This plugin already references: + +- `./skills/` +- `./hooks.json` +- `./.mcp.json` +- `./.app.json` + +### 4. Verify the MCP config + +The MCP config lives at: + +```text +.mcp.json +``` + +It starts the local server with: + +```json +{ + "mcpServers": { + "taskScheduler": { + "command": "python", + "args": ["./scripts/mcp_server.py"], + "cwd": "." + } + } +} +``` + +### 5. Optional marketplace registration + +If you want the plugin to appear in Codex UI ordering, register it in your marketplace file: + +```text +.agents/plugins/marketplace.json +``` + +This repo already includes a starter marketplace entry. + +## Quick Start + +### Run the CLI + +```powershell +python .\scripts\build_schedule.py ` + --input .\scripts\example_tasks.json +``` + +### Start the MCP server directly + +```powershell +python .\scripts\mcp_server.py +``` + +### Use the example data + +Sample input lives at: + +```text +scripts/example_tasks.json +``` + +## Documentation + +- [Getting Started](./docs/GETTING_STARTED.md) +- [MCP Reference](./docs/MCP_REFERENCE.md) +- [Architecture](./docs/ARCHITECTURE.md) +- [Development Guide](./docs/DEVELOPMENT.md) +- [Publishing Guide](./docs/PUBLISHING.md) +- [Contributing](./CONTRIBUTING.md) +- [Security Policy](./SECURITY.md) +- [Privacy Policy](./PRIVACY.md) +- [Terms of Service](./TERMS.md) + +## Current Status + +This plugin is a strong local starter and learning reference. It is already useful for local scheduling and MCP-based planning flows, but a few areas are still intentionally starter-level: + +- `.app.json` integration details +- runtime hook registrations in `hooks.json` +- final production screenshots and branding assets + +## Roadmap Ideas + +- add more MCP tools such as automatic overflow rescheduling +- support recurring tasks and dependency chains +- add export formats beyond markdown +- connect planner output to external task systems +- add repository releases and changelog automation + +## License + +MIT, unless you choose a different license for your public repository. diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/SECURITY.md b/plugins/6Delta9/task-scheduler-codex-plugin/SECURITY.md new file mode 100644 index 0000000..c5db76b --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +## Supported Versions + +Task Scheduler is currently maintained as a single active line on the `main` branch. + +Security fixes, documentation fixes, and dependency updates are applied to the latest version in this repository. + +## Reporting a Vulnerability + +If you believe you have found a security issue in this plugin: + +1. Do not open a public GitHub issue with exploit details. +2. Send a report to `opensource@6delta9.dev`. +3. Include: + - a short description of the issue + - affected files or components + - reproduction steps + - impact assessment if known + +You can also open a GitHub issue for non-sensitive security hardening suggestions that do not expose a live vulnerability: + +https://github.com/6Delta9/task-scheduler-codex-plugin/issues + +## Scope + +This repository is a local-first Codex plugin and MCP server starter. Security review is especially relevant for: + +- shell execution paths +- file path handling +- MCP tool inputs +- third-party dependencies +- future hooks or app integrations + +## Disclosure Expectations + +- I will try to acknowledge reports promptly. +- Public disclosure should wait until the issue is understood and a fix or mitigation is available. +- If a report turns out to be low risk or non-exploitable, it may be handled as a regular improvement instead of a security advisory. diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/assets/icon.png b/plugins/6Delta9/task-scheduler-codex-plugin/assets/icon.png new file mode 100644 index 0000000..ef38184 Binary files /dev/null and b/plugins/6Delta9/task-scheduler-codex-plugin/assets/icon.png differ diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/assets/logo.png b/plugins/6Delta9/task-scheduler-codex-plugin/assets/logo.png new file mode 100644 index 0000000..f436f9a Binary files /dev/null and b/plugins/6Delta9/task-scheduler-codex-plugin/assets/logo.png differ diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot1.png b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot1.png new file mode 100644 index 0000000..e784907 Binary files /dev/null and b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot1.png differ diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot2.png b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot2.png new file mode 100644 index 0000000..14226e3 Binary files /dev/null and b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot2.png differ diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot3.png b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot3.png new file mode 100644 index 0000000..ca028ed Binary files /dev/null and b/plugins/6Delta9/task-scheduler-codex-plugin/assets/screenshot3.png differ diff --git a/plugins/6Delta9/task-scheduler-codex-plugin/skills/task-planner/SKILL.md b/plugins/6Delta9/task-scheduler-codex-plugin/skills/task-planner/SKILL.md new file mode 100644 index 0000000..6dd45e6 --- /dev/null +++ b/plugins/6Delta9/task-scheduler-codex-plugin/skills/task-planner/SKILL.md @@ -0,0 +1,49 @@ +--- +name: task-planner +description: Turn a list of goals, tasks, deadlines, and working constraints into a practical schedule with next actions and follow-ups. +--- + +# Task Planner + +Use this skill when the user wants help organizing work into a schedule. + +## Workflow + +1. Gather the planning window, available hours, deadlines, and any fixed meetings or blocked days. +2. Group the work into concrete tasks with estimated effort and priority. +3. Produce a schedule that is realistic, not just complete. +4. Flag overflow, risky deadlines, and missing information. + +## Output Format + +Return the plan in markdown with these sections: + +- `Summary` +- `Schedule` +- `Follow-Ups` +- `Risks` + +For each scheduled item, include: + +- task name +- planned date +- estimated effort +- short reason for placement + +## Scheduling Rules + +- Put urgent and high-priority work first. +- Avoid filling a day past the stated hour limit. +- Break large work into smaller steps when that makes the plan easier to follow. +- Keep at least one buffer slot when the schedule is tight. +- Call out tasks that do not fit inside the requested window. + +## Script Assist + +When the user provides structured JSON tasks, you can use: + +```powershell +python .\scripts\build_schedule.py --input +``` + +The script builds a first-pass markdown schedule that you can refine in your response. diff --git a/plugins/AlexMi64/codex-project-autopilot/.codex-plugin/plugin.json b/plugins/AlexMi64/codex-project-autopilot/.codex-plugin/plugin.json new file mode 100644 index 0000000..b3446e1 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/.codex-plugin/plugin.json @@ -0,0 +1,49 @@ +{ + "name": "codex-project-autopilot", + "version": "1.0.0", + "description": "ะ›ะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ Codex, ะบะพั‚ะพั€ั‹ะน ะฟะพะผะพะณะฐะตั‚ ะฟั€ะพะนั‚ะธ ะฟัƒั‚ัŒ ะพั‚ ะธะดะตะธ ะดะพ ะณะพั‚ะพะฒะพะณะพ ะฟั€ะพะตะบั‚ะฐ: ะฒะพะฟั€ะพัั‹, ะฟะปะฐะฝ, ั€ะตะฐะปะธะทะฐั†ะธั, ะฟั€ะพะฒะตั€ะบะฐ ะธ ั„ะธะฝะฐะปัŒะฝั‹ะต ะธะฝัั‚ั€ัƒะบั†ะธะธ.", + "author": { + "name": "Morecil", + "email": "vbfbk2010@gmail.com", + "url": "https://vibecode.morecil.ru/ru/" + }, + "homepage": "https://vibecode.morecil.ru/ru/", + "repository": "https://github.com/AlexMi64/codex-project-autopilot", + "license": "MIT", + "keywords": [ + "codex-project-autopilot", + "project-planning", + "site-builder", + "telegram-bot", + "saas-mvp", + "automation-script", + "api-integration", + "codex" + ], + "skills": "./skills/", + "hooks": "./hooks.json", + "interface": { + "displayName": "Codex Project Autopilot", + "shortDescription": "ะŸะพะผะพะณะฐะตั‚ ะฟั€ะตะฒั€ะฐั‚ะธั‚ัŒ ะธะดะตัŽ ะฒ ะฟะพะฝัั‚ะฝั‹ะน ะฟะปะฐะฝ, ั€ะฐะฑะพั‡ะธะน ะฟั€ะพะตะบั‚ ะธ ั„ะธะฝะฐะปัŒะฝั‹ะต ะธะฝัั‚ั€ัƒะบั†ะธะธ", + "longDescription": "Codex Project Autopilot ะฟะพะผะพะณะฐะตั‚ ะฟั€ะพะนั‚ะธ ะฟัƒั‚ัŒ ะพั‚ ะธะดะตะธ ะดะพ ะณะพั‚ะพะฒะพะณะพ ั€ะตะทัƒะปัŒั‚ะฐั‚ะฐ: ะทะฐะดะฐั‘ั‚ ะฟั€ะพัั‚ั‹ะต ะฒะพะฟั€ะพัั‹, ัะพะฑะธั€ะฐะตั‚ ะฟะพะฝัั‚ะฝั‹ะน ะฟะปะฐะฝ, ั…ั€ะฐะฝะธั‚ ัะพัั‚ะพัะฝะธะต ะฟั€ะพะตะบั‚ะฐ ะฒ ั‚ะตะบัƒั‰ะตะน ะฟะฐะฟะบะต, ะฟะพะผะพะณะฐะตั‚ ั ะฟั€ะพะตะบั‚ะธั€ะพะฒะฐะฝะธะตะผ, ั€ะตะฐะปะธะทะฐั†ะธะตะน, ะฟั€ะพะฒะตั€ะบะพะน ะธ ะฟะพะดะณะพั‚ะพะฒะบะพะน ะบ ะทะฐะฟัƒัะบัƒ. ะŸะพะดั…ะพะดะธั‚ ะดะปั ัะฐะนั‚ะพะฒ, ั‚ะตะปะตะณั€ะฐะผ-ะฑะพั‚ะพะฒ, ะฝะตะฑะพะปัŒัˆะธั… ัะตั€ะฒะธัะพะฒ, ัะบั€ะธะฟั‚ะพะฒ ะธ ะธะฝั‚ะตะณั€ะฐั†ะธะน. ะ•ัะปะธ ะฝัƒะถะฝะพ, ะธัะฟะพะปัŒะทัƒะตั‚ ะฒัั‚ั€ะพะตะฝะฝั‹ะต ั€ะพะปะธ ะธ ะฟะพะผะพะณะฐะตั‚ ะฝะพะฒะธั‡ะบัƒ ะฟะพะฝัั‚ัŒ, ั‡ั‚ะพ ะดะตะปะฐั‚ัŒ ะดะฐะปัŒัˆะต ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ.", + "developerName": "Morecil", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Read", + "Write" + ], + "websiteURL": "https://vibecode.morecil.ru/ru/", + "privacyPolicyURL": "https://vibecode.morecil.ru/ru/privacy/", + "termsOfServiceURL": "https://vibecode.morecil.ru/ru/terms/", + "defaultPrompt": [ + "ะะฐั‡ะฐั‚ัŒ ะฝะพะฒั‹ะน ะฟั€ะพะตะบั‚ ั ะฝัƒะปั", + "ะŸั€ะพะดะพะปะถะธั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะฟะพ ั‚ะตะบัƒั‰ะตะผัƒ ะฟั€ะพะตะบั‚ัƒ", + "ะŸะพะดะณะพั‚ะพะฒะธั‚ัŒ ะทะฐะฟัƒัะบ, ะฝะฐัั‚ั€ะพะนะบะธ ะธ ัะตะบั€ะตั‚ั‹" + ], + "brandColor": "#182C61", + "composerIcon": "./assets/autonomous-project-agent.svg", + "logo": "./assets/autonomous-project-agent.svg", + "screenshots": [] + } +} diff --git a/plugins/AlexMi64/codex-project-autopilot/LICENSE b/plugins/AlexMi64/codex-project-autopilot/LICENSE new file mode 100644 index 0000000..23877be --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Morecil + +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/plugins/AlexMi64/codex-project-autopilot/README.md b/plugins/AlexMi64/codex-project-autopilot/README.md new file mode 100644 index 0000000..514965a --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/README.md @@ -0,0 +1,511 @@ +# Codex Project Autopilot + +ะ›ะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ ะดะปั Codex, ะบะพั‚ะพั€ั‹ะน ะฟั€ะตะฒั€ะฐั‰ะฐะตั‚ ัั‹ั€ัƒัŽ ะธะดะตัŽ ะฒ ะฟะพะฝัั‚ะฝั‹ะน ะฟั€ะพะตะบั‚ะฝั‹ะน ะผะฐั€ัˆั€ัƒั‚: ะฒะพะฟั€ะพัั‹, brief, ะฟะปะฐะฝ, ั€ะตะฐะปะธะทะฐั†ะธั, ะฟั€ะพะฒะตั€ะบะฐ ะธ ั„ะธะฝะฐะปัŒะฝั‹ะน handoff. + +ะญั‚ะพ ะฝะต ะฟั€ะพัั‚ะพ ะฝะฐะฑะพั€ ะฟั€ะพะผะฟั‚ะพะฒ. ะŸะปะฐะณะธะฝ ะฒะตะดั‘ั‚ ะฟั€ะพะตะบั‚ ะฟะพ ัˆะฐะณะฐะผ, ั…ั€ะฐะฝะธั‚ ะบะพะฝั‚ะตะบัั‚ ะฒ workspace, ะฝะต ะดะฐั‘ั‚ ะฟะตั€ะตัะบะพั‡ะธั‚ัŒ ั‡ะตั€ะตะท ะฒะฐะถะฝั‹ะต ัั‚ะฐะฟั‹ ะธ ะฟะพะผะพะณะฐะตั‚ ะดะพะฒะพะดะธั‚ัŒ ั€ะตะทัƒะปัŒั‚ะฐั‚ ะดะพ ั€ะฐะฑะพั‡ะตะณะพ ัะพัั‚ะพัะฝะธั ะฑะตะท ะฟะพัั‚ะพัะฝะฝะพะณะพ ั€ัƒั‡ะฝะพะณะพ ะฟะพะดั‚ะฐะปะบะธะฒะฐะฝะธั. + +ะŸะพะดะดะตั€ะถะธะฒะฐะตะผั‹ะต ะฟะปะฐั‚ั„ะพั€ะผั‹ ะดะปั ะปะพะบะฐะปัŒะฝะพะน ั€ะฐะฑะพั‚ั‹: macOS, Linux ะธ Windows. + +## ะ—ะฐั‡ะตะผ ะพะฝ ะฝัƒะถะตะฝ + +ะžะฑั‹ั‡ะฝั‹ะน ัั†ะตะฝะฐั€ะธะน ั€ะฐะฑะพั‚ั‹ ั ะ˜ะ˜ ะฒั‹ะณะปัะดะธั‚ ั‚ะฐะบ: + +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟะธัˆะตั‚ ะธะดะตัŽ +- ะผะพะดะตะปัŒ ะพั‚ะฒะตั‡ะฐะตั‚ ัะปะธัˆะบะพะผ ะพะฑั‰ะพ ะธะปะธ ัั€ะฐะทัƒ ะฟั€ั‹ะณะฐะตั‚ ะฒ ะบะพะด +- ะฒะฐะถะฝั‹ะต ั‚ั€ะตะฑะพะฒะฐะฝะธั ั‚ะตั€ััŽั‚ัั ะฟะพ ั…ะพะดัƒ ะดะธะฐะปะพะณะฐ +- ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ, ะดะธะทะฐะนะฝ, ะฑะตะทะพะฟะฐัะฝะพัั‚ัŒ ะธ handoff ะพะบะฐะทั‹ะฒะฐัŽั‚ัั ะฝะตะดะพะณะพะฒะพั€ั‘ะฝะฝั‹ะผะธ +- ะฝะฐ ั„ะธะฝะฐะปะต ะฒัั‘ ั€ะฐะฒะฝะพ ะฟั€ะธั…ะพะดะธั‚ัั ะผะฝะพะณะพ ะฟะตั€ะตะดะตะปั‹ะฒะฐั‚ัŒ ั€ัƒะบะฐะผะธ + +ะญั‚ะพั‚ ะฟะปะฐะณะธะฝ ั€ะตัˆะฐะตั‚ ะธะผะตะฝะฝะพ ัั‚ัƒ ะฟั€ะพะฑะปะตะผัƒ. ะžะฝ ะดะพะฑะฐะฒะปัะตั‚ ัั‚ั€ัƒะบั‚ัƒั€ัƒ, ะฟะฐะผัั‚ัŒ ะฟั€ะพะตะบั‚ะฐ, ั€ะพะปะธ, ะฟั€ะพะฒะตั€ะบะธ ะธ ะถั‘ัั‚ะบะธะน ะผะฐั€ัˆั€ัƒั‚ ั€ะฐะฑะพั‚ั‹. + +## ะงั‚ะพ ะดะตะปะฐะตั‚ ะฟะปะฐะณะธะฝ + +- ะฟั€ะธะฝะธะผะฐะตั‚ ะธะดะตัŽ ะฟั€ะพะตะบั‚ะฐ ะธ ะฟะตั€ะตะฒะพะดะธั‚ ะตั‘ ะฒ ะฟะพะฝัั‚ะฝั‹ะน ั€ะฐะฑะพั‡ะธะน ัั†ะตะฝะฐั€ะธะน +- ะทะฐะดะฐั‘ั‚ ะฟั€ะพัั‚ั‹ะต ะฝะฐะฒะพะดัั‰ะธะต ะฒะพะฟั€ะพัั‹ ะฒ ั„ะพั€ะผะฐั‚ะต ะบะฒะธะทะฐ +- ะตัะปะธ ะฟะพัะปะต ะฟะตั€ะฒั‹ั… ะพั‚ะฒะตั‚ะพะฒ ะธะฝั„ะพั€ะผะฐั†ะธะธ ะผะฐะปะพ, ะทะฐะดะฐั‘ั‚ ะตั‰ั‘ ะพะดะฝัƒ ะบะพั€ะพั‚ะบัƒัŽ ะฒะพะปะฝัƒ ัƒั‚ะพั‡ะฝััŽั‰ะธั… ะฒะพะฟั€ะพัะพะฒ +- ะพะฑัŠััะฝัะตั‚ ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ, ะทะฐั‡ะตะผ ะฝัƒะถะฝั‹ ัั‚ะธ ัƒั‚ะพั‡ะฝะตะฝะธั ะธ ะฝะฐ ั‡ั‚ะพ ะพะฝะธ ะฒะปะธััŽั‚ +- ะพั‚ะดะตะปัŒะฝะพ ะฒั‹ััะฝัะตั‚, ั‡ั‚ะพ ะดะตะปะฐะตั‚ ะฟั€ะพะตะบั‚ ัƒะฝะธะบะฐะปัŒะฝั‹ะผ ะธ ะฝะฐ ั‡ั‚ะพ ะพะฝ ะฝะต ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ะฟะพั…ะพะถ +- ะพะฟั€ะตะดะตะปัะตั‚ ั‚ะธะฟ ะฟั€ะพะตะบั‚ะฐ ะธ ะฟะพะดั…ะพะดัั‰ะธะน ะผะฐั€ัˆั€ัƒั‚ ั€ะตะฐะปะธะทะฐั†ะธะธ +- ัะพะฑะธั€ะฐะตั‚ ะฟั€ะพะตะบั‚ะฝั‹ะน ะบะพะฝั‚ะตะบัั‚ ะธ ะฟะปะฐะฝ ะฒ ะพั‚ะดะตะปัŒะฝั‹ะต ะฐั€ั‚ะตั„ะฐะบั‚ั‹ +- ะฟั€ะตะดะปะฐะณะฐะตั‚ 3 ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ: ะผะธะฝะธะผัƒะผ, ะพะฟั‚ะธะผะฐะปัŒะฝะพ ะธ ั ะทะฐะฟะฐัะพะผ +- ั€ะตะบะพะผะตะฝะดัƒะตั‚ ะพะดะธะฝ ะฒะฐั€ะธะฐะฝั‚ ะธ ะพะฑัŠััะฝัะตั‚ ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ, ะฟะพั‡ะตะผัƒ +- ะดะตะปะธั‚ ั€ะฐะฑะพั‚ัƒ ะฟะพ ั€ะพะปัะผ: ะฐะฝะฐะปะธั‚ะธะบะฐ, ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ, ะดะธะทะฐะนะฝ, ั„ั€ะพะฝั‚ะตะฝะด, ะฑัะบะตะฝะด, ะฑะฐะทะฐ, ะฐะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธั, QA, ะดะตะฟะปะพะน +- ะฝะต ะฝะฐั‡ะธะฝะฐะตั‚ ั€ะตะฐะปะธะทะฐั†ะธัŽ, ะฟะพะบะฐ ะฟะปะฐะฝ ะฝะต ะฟะพะดั‚ะฒะตั€ะถะดั‘ะฝ +- ะทะฐะผะพั€ะฐะถะธะฒะฐะตั‚ ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝั‹ะน ะฟะปะฐะฝ, ั‡ั‚ะพะฑั‹ ะพะฝ ะฝะต ะฟะตั€ะตะทะฐะฟะธัั‹ะฒะฐะปัั ัะปัƒั‡ะฐะนะฝะพ +- ะฟั€ะพะฒะพะดะธั‚ ะฟั€ะพะฒะตั€ะบัƒ ะฟะตั€ะตะด ั„ะธะฝะฐะปัŒะฝั‹ะผ handoff +- ัะพะฑะธั€ะฐะตั‚ ั‡ะตะบะปะธัั‚ ะฟะพ ัะตะบั€ะตั‚ะฐะผ, env ะธ ั€ัƒั‡ะฝั‹ะผ ัˆะฐะณะฐะผ +- ะฒัˆะธะฒะฐะตั‚ ะฑะตะทะพะฟะฐัะฝั‹ะต ะดะตั„ะพะปั‚ั‹ ะฒ ะฑั€ะธั„, ะฟะปะฐะฝ, ะฑัะบะตะฝะด, ะฑะฐะทัƒ, QA ะธ handoff +- ะฝะฐะฟะพะผะธะฝะฐะตั‚ ะฟั€ะพ ะผะธะฝะธะผะธะทะฐั†ะธัŽ ะดะฐะฝะฝั‹ั…, parameterized queries / ORM, ั€ะฐะทะดะตะปะตะฝะธะต client/server ะบะปัŽั‡ะตะน ะธ ะฑะฐะทะพะฒัƒัŽ ะฟั€ะพะฒะตั€ะบัƒ ะทะฐะฒะธัะธะผะพัั‚ะตะน + +## ะฃะฝะธะบะฐะปัŒะฝะพัั‚ัŒ ะธ ะดะธะทะฐะนะฝ + +ะŸะปะฐะณะธะฝ ะฝะต ะธัั…ะพะดะธั‚ ะธะท ะธะดะตะธ, ั‡ั‚ะพ ะฒัะต ะฟั€ะพะตะบั‚ั‹ ะดะพะปะถะฝั‹ ะฒั‹ะณะปัะดะตั‚ัŒ ะพะดะธะฝะฐะบะพะฒะพ ะธะปะธ ะฑั‹ั‚ัŒ ะพะดะธะฝะฐะบะพะฒะพ โ€œะบั€ะตะฐั‚ะธะฒะฝั‹ะผะธโ€. + +ะžะฝ ั€ะฐะทะปะธั‡ะฐะตั‚: + +- ัะฟะพะบะพะนะฝั‹ะน ะฟั€ะพะดัƒะบั‚ะพะฒั‹ะน ะธะฝั‚ะตั€ั„ะตะนั +- ะฒั‹ั€ะฐะทะธั‚ะตะปัŒะฝั‹ะน ะผะฐั€ะบะตั‚ะธะฝะณะพะฒั‹ะน ัะบั€ะฐะฝ +- ะดะตะนัั‚ะฒะธั‚ะตะปัŒะฝะพ ัะผะตะปะพะต ะฒะธะทัƒะฐะปัŒะฝะพะต ะฝะฐะฟั€ะฐะฒะปะตะฝะธะต + +ะ˜ ะฒั‹ะฑะธั€ะฐะตั‚ ัั‚ะพ ะฝะต ะฟะพ ะผะพะดะต, ะฐ ะฟะพ ะทะฐะดะฐั‡ะต ะฟั€ะพะตะบั‚ะฐ. + +ะ”ะปั ัั‚ะพะณะพ ะพะฝ: + +- ั„ะธะบัะธั€ัƒะตั‚ `project DNA` ะธ ะฟั€ะฐะฒะธะปะฐ ัƒะฝะธะบะฐะปัŒะฝะพัั‚ะธ +- ะพั‚ะดะตะปัŒะฝะพ ะพะฟั€ะตะดะตะปัะตั‚ ั…ะฐั€ะฐะบั‚ะตั€ ะฟั€ะพะดัƒะบั‚ะฐ, ะฒะธะทัƒะฐะปัŒะฝัƒัŽ ัะผะตะปะพัั‚ัŒ ะธ ัะทั‹ะบ ั„ะพั€ะผ +- ะทะฐะฟั€ะตั‰ะฐะตั‚ generic-ั€ะตัˆะตะฝะธั ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ +- ัƒะผะตะตั‚ ัƒั‡ะธั‚ั‹ะฒะฐั‚ัŒ ะปะพะบะฐะปัŒะฝั‹ะต style-skills, moodboard, brand guide ะธ `design-system.json` +- ะฝะต ะดะฐั‘ั‚ ะฟั€ะตะฒั€ะฐั‰ะฐั‚ัŒ ะบะฐะถะดั‹ะน ะฟั€ะพะตะบั‚ ะฒ โ€œAwwwards-ะปะตะฝะดะธะฝะณโ€ ะฑะตะท ะฟั€ะธั‡ะธะฝั‹ + +ะžั‚ะดะตะปัŒะฝะพ ะทะฐั„ะธะบัะธั€ะพะฒะฐะฝะพ ะฟั€ะฐะฒะธะปะพ ั‚ะธะฟะพะณั€ะฐั„ะธะบะธ: + +- ะตัะปะธ ะธะฝั‚ะตั€ั„ะตะนั ะธ ะบะพะฝั‚ะตะฝั‚ ะฝะฐ ั€ัƒััะบะพะผ, ะฟะปะฐะณะธะฝ ะดะพะปะถะตะฝ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ัˆั€ะธั„ั‚ั‹ ั ะฟะพะดะดะตั€ะถะบะพะน ะบะธั€ะธะปะปะธั†ั‹ +- ะพั‚ััƒั‚ัั‚ะฒะธะต ะบะธั€ะธะปะปะธั†ั‹ ัƒ display/body ัˆั€ะธั„ั‚ะฐ ัั‡ะธั‚ะฐะตั‚ัั ะพัˆะธะฑะบะพะน ะบะฐั‡ะตัั‚ะฒะฐ, ะฐ ะฝะต โ€œะผะตะปะบะพะน ะดะตั‚ะฐะปัŒัŽ ะฝะฐ ะฟะพั‚ะพะผโ€ + +## ะ”ะปั ะบะฐะบะธั… ะฟั€ะพะตะบั‚ะพะฒ ะฟะพะดั…ะพะดะธั‚ + +- ะปะตะฝะดะธะฝะณะธ ะธ ะฟั€ะพะดัƒะบั‚ะพะฒั‹ะต ัะฐะนั‚ั‹ +- Telegram- ะธ AI-ะฑะพั‚ั‹ +- SaaS MVP ะธ ะบะฐะฑะธะฝะตั‚ั‹ +- automation-ัะบั€ะธะฟั‚ั‹ +- API-ะธะฝั‚ะตะณั€ะฐั†ะธะธ ะธ ะฒะพั€ะบะตั€ั‹ +- ัะผะตัˆะฐะฝะฝั‹ะต ะฟั€ะพะตะบั‚ั‹, ะณะดะต ะตัั‚ัŒ ะฝะตัะบะพะปัŒะบะพ ะฟะพะดัะธัั‚ะตะผ ะพะดะฝะพะฒั€ะตะผะตะฝะฝะพ + +ะะฐะฟั€ะธะผะตั€: + +- Telegram-ะฑะพั‚ + ะฐะดะผะธะฝ-ะฟะฐะฝะตะปัŒ +- SaaS + ะฑะฐะทะฐ + ะฐะฒั‚ะพั€ะธะทะฐั†ะธั +- ะปะตะฝะดะธะฝะณ + ั„ะพั€ะผะฐ ะทะฐัะฒะพะบ + ะฟั€ะพัั‚ะฐั ะฐะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธั +- API-ะฒะพั€ะบะตั€ + ะปะพะณะธั€ะพะฒะฐะฝะธะต + ั€ัƒั‡ะฝะพะน handoff + +## ะšะฐะบ ะพะฝ ั€ะฐะฑะพั‚ะฐะตั‚ + +ะŸะปะฐะณะธะฝ ะฒะตะดั‘ั‚ ะฟั€ะพะตะบั‚ ะฟะพ ั„ะธะบัะธั€ะพะฒะฐะฝะฝั‹ะผ ั„ะฐะทะฐะผ: + +1. `discovery` + ะกะพะฑะธั€ะฐะตั‚ ั‚ั€ะตะฑะพะฒะฐะฝะธั ั‡ะตั€ะตะท ะบะพั€ะพั‚ะบะธะน ะธ ะฟะพะฝัั‚ะฝั‹ะน ะบะฒะธะท. + +2. `planning` + ะคะพั€ะผะธั€ัƒะตั‚ brief, product intelligence, ั‚ะตั…ะฝะธั‡ะตัะบะธะน ะบะพะฝั‚ะตะบัั‚, 3 ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ ะธ ั€ะตะบะพะผะตะฝะดัƒะตะผั‹ะน ะผะฐั€ัˆั€ัƒั‚. + +3. `approval` + ะŸะพะบะฐะทั‹ะฒะฐะตั‚ ะฒะฐั€ะธะฐะฝั‚ั‹ ะฟะปะฐะฝะฐ, ะพะฑัŠััะฝัะตั‚ ั€ะฐะทะฝะธั†ัƒ ะธ ะฟั€ะพัะธั‚ ะพะดะฝะพ ัะฒะฝะพะต ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะธะต. + +4. `execution` + ะ ะตะฐะปะธะทัƒะตั‚ ะฟั€ะพะตะบั‚ ะฟะพ ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝะพะผัƒ ะผะฐั€ัˆั€ัƒั‚ัƒ. + +5. `verification` + ะŸั€ะพะฒะตั€ัะตั‚, ั‡ั‚ะพ ะฟั€ะพะตะบั‚ ะฝะต ั€ะฐะทะฒะฐะปะธะฒะฐะตั‚ัั ะฟะพ ะพัะฝะพะฒะฝั‹ะผ ัั†ะตะฝะฐั€ะธัะผ. + +6. `handoff` + ะ“ะพั‚ะพะฒะธั‚ ั„ะธะฝะฐะปัŒะฝั‹ะต ะธะฝัั‚ั€ัƒะบั†ะธะธ: ั‡ั‚ะพ ัะดะตะปะฐะฝะพ, ั‡ั‚ะพ ะพัั‚ะฐะปะพััŒ ั€ัƒะบะฐะผะธ, ะบะฐะบะธะต ัะตะบั€ะตั‚ั‹ ะธ env ะฝัƒะถะฝั‹, ะบะฐะบ ะทะฐะฟัƒัะบะฐั‚ัŒ ะธ ะดะตะฟะปะพะธั‚ัŒ. + +## ะŸะพั‡ะตะผัƒ ะพะฝ ะฟะพะปะตะทะฝะตะต ะพะฑั‹ั‡ะฝะพะณะพ ะฟั€ะพะผะฟั‚ะฐ + +- ะฝะต ั‚ะตั€ัะตั‚ ะบะพะฝั‚ะตะบัั‚ ะผะตะถะดัƒ ัะตััะธัะผะธ +- ะฝะต ะฝะฐั‡ะธะฝะฐะตั‚ ะบะพะดะธั‚ัŒ ัะปะธัˆะบะพะผ ั€ะฐะฝะพ +- ะฝะต ะดะฐั‘ั‚ ัะผะตัˆะธะฒะฐั‚ัŒ ะฐะฝะฐะปะธะท, ะดะธะทะฐะนะฝ ะธ ั€ะตะฐะปะธะทะฐั†ะธัŽ ะฒ ะพะดะฝัƒ ะบะฐัˆัƒ +- ะฟะพะผะพะณะฐะตั‚ ะฝะต ัะบะฐั‚ั‹ะฒะฐั‚ัŒัั ะฒ generic-ั€ะตัˆะตะฝะธั +- ัะฝะธะถะฐะตั‚ ั€ะธัะบ ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฝะพะณะพ ั…ะฐะพัะฐ +- ะดะตะปะฐะตั‚ ั„ะธะฝะฐะปัŒะฝั‹ะน handoff ั‡ะฐัั‚ัŒัŽ ะฟั€ะพั†ะตััะฐ, ะฐ ะฝะต โ€œะดะพะดะตะปะบะพะน ะฒ ะบะพะฝั†ะตโ€ + +## ะญะบะพะฝะพะผะธั ั‚ะพะบะตะฝะพะฒ + +ะžะดะฝะฐ ะธะท ะณะปะฐะฒะฝั‹ั… ะทะฐะดะฐั‡ ะฟะปะฐะณะธะฝะฐ โ€” ะฝะต ั‚ะพะปัŒะบะพ ัƒะปัƒั‡ัˆะฐั‚ัŒ ะบะฐั‡ะตัั‚ะฒะพ, ะฝะพ ะธ ัƒะผะตะฝัŒัˆะฐั‚ัŒ ั€ะฐัั…ะพะด ะบะพะฝั‚ะตะบัั‚ะฐ. + +ะ”ะปั ัั‚ะพะณะพ ะพะฝ ะธัะฟะพะปัŒะทัƒะตั‚ ั‚ั€ั‘ั…ัะปะพะนะฝั‹ะน ั€ะตะถะธะผ ะฟะฐะผัั‚ะธ: + +- `phase-card.md` + ัะฐะผั‹ะน ะบะพั€ะพั‚ะบะธะน ั„ะฐะทะพะฒั‹ะน ัะฝะธะผะพะบ: ั‡ั‚ะพ ะดะตะปะฐั‚ัŒ ะฟั€ัะผะพ ัะตะนั‡ะฐั ะธ ะบะพะณะดะฐ ะฒะพะพะฑั‰ะต ะผะพะถะฝะพ ะพั‚ะบั€ั‹ะฒะฐั‚ัŒ docs +- `ultra-context.md` + ะบะพั€ะพั‚ะบะฐั ะฒั‹ะถะธะผะบะฐ ะดะปั ั‚ะตะบัƒั‰ะตะณะพ ัˆะฐะณะฐ +- `context-bundle.md` + ั„ะฐะทะพะฒั‹ะน bundle ะฑะตะท ะปะธัˆะฝะธั… ั€ะฐะทะดะตะปะพะฒ ะฝะต ะฟะพ ั‚ะตะบัƒั‰ะตะผัƒ ัั‚ะฐะฟัƒ + +ะ˜ะดะตั ะฒ ั‚ะพะผ, ั‡ั‚ะพ ะฐะณะตะฝั‚ ัะฝะฐั‡ะฐะปะฐ ั‡ะธั‚ะฐะตั‚ ะผะธะฝะธะผัƒะผ, ะฟะพั‚ะพะผ ั‚ะพะปัŒะบะพ ะฝัƒะถะฝัƒัŽ ั„ะฐะทะพะฒัƒัŽ ัะฒะพะดะบัƒ, ะธ ั‚ะพะปัŒะบะพ ะฟะพั‚ะพะผ ะฟั€ะธ ะฝะตะพะฑั…ะพะดะธะผะพัั‚ะธ ะพั‚ะบั€ั‹ะฒะฐะตั‚ ะดะพะบัƒะผะตะฝั‚ั‹ ะธะปะธ knowledge packs. ะ—ะฐ ัั‡ั‘ั‚ ัั‚ะพะณะพ ะฟะปะฐะณะธะฝ ะฒ ั€ะตะฐะปัŒะฝะพะน ั€ะฐะฑะพั‚ะต ะผะพะถะตั‚ ั‚ั€ะฐั‚ะธั‚ัŒ ะทะฐะผะตั‚ะฝะพ ะผะตะฝัŒัˆะต ั‚ะพะบะตะฝะพะฒ, ั‡ะตะผ ะพะฑั‹ั‡ะฝั‹ะน ั€ะตะถะธะผ โ€œะฟั€ะพั‡ะธั‚ะฐะน ะฒัั‘ ะธ ะฟะพะดัƒะผะฐะน ะตั‰ั‘ ั€ะฐะทโ€. + +## ะงั‚ะพ ั…ั€ะฐะฝะธั‚ัั ะฒ ะฟั€ะพะตะบั‚ะต + +ะŸะปะฐะณะธะฝ ะฒะตะดั‘ั‚ ะปะพะบะฐะปัŒะฝัƒัŽ ะฟะฐะผัั‚ัŒ ะฟั€ะพะตะบั‚ะฐ ะฒ ะฟะฐะฟะบะต `.codex-agent/`. + +ะ’ะฐะถะฝะพ: + +- `.codex-agent` ัะพะทะดะฐั‘ั‚ัั ะฒ ั‚ะตะบัƒั‰ะตะน ะฟะฐะฟะบะต ะฟั€ะพะตะบั‚ะฐ +- ะพะฝ ะฝะต ั…ั€ะฐะฝะธั‚ัั ะณะปะพะฑะฐะปัŒะฝะพ +- ะณะปะพะฑะฐะปัŒะฝะพ ัƒัั‚ะฐะฝะฐะฒะปะธะฒะฐะตั‚ัั ั‚ะพะปัŒะบะพ ัะฐะผ ะฟะปะฐะณะธะฝ ะฒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะธะน marketplace Codex +- ัƒ ะบะฐะถะดะพะณะพ ะฟั€ะพะตะบั‚ะฐ ัะฒะพะธ ะปะพะบะฐะปัŒะฝั‹ะต ะฐั€ั‚ะตั„ะฐะบั‚ั‹ ะธ ัะฒะพั‘ ัะพัั‚ะพัะฝะธะต + +ะขะฐะผ ัะพั…ั€ะฐะฝััŽั‚ัั: + +- ะบะฒะธะท ะธ ะพั‚ะฒะตั‚ั‹ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั +- brief ะฟั€ะพะตะบั‚ะฐ +- ะฟั€ะพะดัƒะบั‚ะพะฒั‹ะน ะธ ั‚ะตั…ะฝะธั‡ะตัะบะธะน ะบะพะฝั‚ะตะบัั‚ +- ะฐะบั‚ะธะฒะฝั‹ะต ั€ะตัˆะตะฝะธั ะฟะพ ั‚ะตะบัƒั‰ะตะน ั„ะฐะทะต +- ะฟะปะฐะฝ ั€ะตะฐะปะธะทะฐั†ะธะธ +- ะดะธะทะฐะนะฝ-ะฝะฐะฟั€ะฐะฒะปะตะฝะธะต +- ะปะพะณ ะฒั‹ะฟะพะปะฝะตะฝะธั +- ะพั‚ั‡ั‘ั‚ ะฟะพ ะฟั€ะพะฒะตั€ะบะต +- ั‡ะตะบะปะธัั‚ ะฟะพ ัะตะบั€ะตั‚ะฐะผ ะธ env +- ั„ะธะฝะฐะปัŒะฝั‹ะน handoff +- ัะพัั‚ะพัะฝะธะต ะฟั€ะพะตะบั‚ะฐ ะฒ `state.json` +- ะทะฐะผะพั€ะพะถะตะฝะฝั‹ะน ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝั‹ะน ะฟะปะฐะฝ ะฒ `approval-snapshot.json` + +ะญั‚ะพ ะฟะพะทะฒะพะปัะตั‚ ะฟั€ะพะดะพะปะถะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะฑะตะท ะฟะพัั‚ะพัะฝะฝะพะณะพ ะฒะพััั‚ะฐะฝะพะฒะปะตะฝะธั ะบะพะฝั‚ะตะบัั‚ะฐ ั ะฝัƒะปั. + +## ะ’ัั‚ั€ะพะตะฝะฝั‹ะต ั€ะพะปะธ + +ะŸะปะฐะณะธะฝ ะธัะฟะพะปัŒะทัƒะตั‚ ั€ะพะปัŒ-ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ ะธ ะฝะฐะฑะพั€ ัะฟะตั†ะธะฐะปะธะทะธั€ะพะฒะฐะฝะฝั‹ั… ั€ะพะปะตะน: + +- `project-discovery` +- `solution-architect` +- `design-director` +- `frontend-builder` +- `backend-builder` +- `database-designer` +- `automation-builder` +- `qa-reviewer` +- `deploy-operator` + +ะ•ัะปะธ ะฒ ัั€ะตะดะต ัƒะถะต ัƒัั‚ะฐะฝะพะฒะปะตะฝั‹ ะฟะพะดั…ะพะดัั‰ะธะต skills, ะฟะปะฐะณะธะฝ ัั‚ะฐั€ะฐะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะธั… ะบะฐะบ ัƒัะธะปะธั‚ะตะปะธ. ะ•ัะปะธ ะธั… ะฝะตั‚, ะพะฝ ะฟั€ะพะดะพะปะถะฐะตั‚ ั€ะฐะฑะพั‚ัƒ ะฒัั‚ั€ะพะตะฝะฝั‹ะผะธ ั€ะพะปัะผะธ. + +## Morecil Role System + +ะ’ะฝัƒั‚ั€ะธ ะฟะปะฐะณะธะฝะฐ ั€ะพะปะธ ะพะฟะธัะฐะฝั‹ ะฟะพ ัะพะฑัั‚ะฒะตะฝะฝะพะน ัะธัั‚ะตะผะต `Morecil Role System`. + +ะญั‚ะพ ะทะฝะฐั‡ะธั‚, ั‡ั‚ะพ ัƒ ะบะฐะถะดะพะน ั€ะพะปะธ ะตัั‚ัŒ: + +- ะผะธััะธั +- ะบะพะฝั‚ั€ะฐะบั‚ +- ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ะต ะฐั€ั‚ะตั„ะฐะบั‚ั‹ +- ะบั€ะธั‚ะตั€ะธะธ ะณะพั‚ะพะฒะฝะพัั‚ะธ +- handoff ัะปะตะดัƒัŽั‰ะตะน ั€ะพะปะธ + +ะ ะพะปะธ ะฝะต ะบะพะฟะธั€ัƒัŽั‚ ั‡ัƒะถะธะต prompt-ะฝะฐะฑะพั€ั‹ ะพะดะธะฝ ะฒ ะพะดะธะฝ. ะžะฝะธ ัะพะฑั€ะฐะฝั‹ ะฟะพะด ัั‚ะธะปัŒ ั€ะฐะฑะพั‚ั‹ ัั‚ะพะณะพ ะฟะปะฐะณะธะฝะฐ: + +- ะผะตะฝัŒัˆะต ั…ะฐะพัะฐ +- ะผะตะฝัŒัˆะต generic-ั€ะตัˆะตะฝะธะน +- ะฑะพะปัŒัˆะต ะฟะพะฝัั‚ะฝะพัั‚ะธ ะดะปั ะฝะพะฒะธั‡ะบะฐ +- ะฑะพะปัŒัˆะต ะบะพะฝั‚ั€ะพะปั ะฝะฐะด scope, quality ะธ handoff + +ะ”ะพะฟะพะปะฝะธั‚ะตะปัŒะฝะพ ัƒ ะฟะปะฐะณะธะฝะฐ ะตัั‚ัŒ [SOULS.md](/Users/a/tgbot/codex-project-autopilot/SOULS.md) โ€” ะฒะตั€ั…ะฝะตัƒั€ะพะฒะฝะตะฒั‹ะน ะบะฐะฝะพะฝ ั€ะพะปะตะน ะธ ะฟั€ะธะฝั†ะธะฟะพะฒ. ะžะฝ ะทะฐะดะฐั‘ั‚ ะฝะต ั‚ะพะปัŒะบะพ ะบะพะฝั‚ั€ะฐะบั‚ั‹, ะฝะพ ะธ โ€œั…ะฐั€ะฐะบั‚ะตั€ ะผั‹ัˆะปะตะฝะธัโ€ ะบะพะผะฐะฝะดั‹, ั‡ั‚ะพะฑั‹ ะฟั€ะพะตะบั‚ั‹ ะฝะต ัะฒะฐะปะธะฒะฐะปะธััŒ ะฒ ะพะดะธะฝะฐะบะพะฒัƒัŽ ัˆะฐะฑะปะพะฝะฝัƒัŽ ะณะตะฝะตั€ะฐั†ะธัŽ. + +## Orchestration Modes + +ะŸะปะฐะณะธะฝ ะฟะพะดะดะตั€ะถะธะฒะฐะตั‚ ะดะฒะฐ ั€ะตะถะธะผะฐ ะพั€ะบะตัั‚ั€ะฐั†ะธะธ: + +- `solo` + ะพะดะธะฝ ะฐะณะตะฝั‚ ะฟะพัะปะตะดะพะฒะฐั‚ะตะปัŒะฝะพ ะฒะตะดั‘ั‚ ั€ะพะปะธ ะฒะฝัƒั‚ั€ะธ ะพะดะฝะพะณะพ ะฟะพั‚ะพะบะฐ +- `delegated` + ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ ะผะพะถะตั‚ ั€ะฐะทะดะฐะฒะฐั‚ัŒ ะฝะตะทะฐะฒะธัะธะผั‹ะต ะทะฐะดะฐั‡ะธ ะพั‚ะดะตะปัŒะฝั‹ะผ ะฟะพะด-ะฐะณะตะฝั‚ะฐะผ, ะตัะปะธ ะฟั€ะพะตะบั‚ ัั‚ะพ ะพะฟั€ะฐะฒะดั‹ะฒะฐะตั‚ + +ะญั‚ะพ ะฝัƒะถะฝะพ ะดะปั ัะพัั‚ะฐะฒะฝั‹ั… ะฟั€ะพะตะบั‚ะพะฒ ะฒั€ะพะดะต: + +- Telegram-ะฑะพั‚ + ะฐะดะผะธะฝ-ะฟะฐะฝะตะปัŒ +- SaaS + auth + data layer +- automation + API worker + verification + +ะŸั€ะธ ัั‚ะพะผ ั„ะธะฝะฐะปัŒะฝั‹ะน ะบะพะฝั‚ั€ะพะปัŒ, scope ะธ handoff ะฒัั‘ ั€ะฐะฒะฝะพ ะพัั‚ะฐัŽั‚ัั ัƒ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ะฐ. + +ะ’ `delegated` ั€ะตะถะธะผะต ะฟะปะฐะณะธะฝ ั‚ะตะฟะตั€ัŒ ั„ะพั€ะผะธั€ัƒะตั‚ ะดะปั ั€ะพะปะตะน ะณะพั‚ะพะฒั‹ะต `delegation packets`: + +- ั‡ั‚ะพ ั‡ะธั‚ะฐั‚ัŒ ัะฝะฐั‡ะฐะปะฐ +- ั‡ั‚ะพ ะธะผะตะฝะฝะพ ะผะพะถะฝะพ ะผะตะฝัั‚ัŒ +- ั‡ั‚ะพ ั€ะพะปัŒ ะพะฑัะทะฐะฝะฐ ะฒะตั€ะฝัƒั‚ัŒ +- ะฒ ะบะฐะบะพะผ ั„ะพั€ะผะฐั‚ะต ะดะตะปะฐั‚ัŒ handoff ะพะฑั€ะฐั‚ะฝะพ + +## ะ’ะฝัƒั‚ั€ะธ ะฟะปะฐะณะธะฝะฐ + +ะŸะปะฐะณะธะฝ ะพะฟะธั€ะฐะตั‚ัั ะฝะต ั‚ะพะปัŒะบะพ ะฝะฐ skills, ะฝะพ ะธ ะฝะฐ ะฝะฐะฑะพั€ ะฒะฝัƒั‚ั€ะตะฝะฝะธั… ะผะตั…ะฐะฝะธะทะผะพะฒ: + +- knowledge packs + ะปะพะบะฐะปัŒะฝั‹ะต ะฟั€ะฐะฒะธะปะฐ ะธ best practices ะฟะพะด ะบะพะฝะบั€ะตั‚ะฝั‹ะต ั‚ะธะฟั‹ ะทะฐะดะฐั‡ +- playbooks + ะผะฐั€ัˆั€ัƒั‚ั‹ ั€ะตะฐะปะธะทะฐั†ะธะธ ะดะปั ั€ะฐะทะฝั‹ั… ะฐั€ั…ะตั‚ะธะฟะพะฒ ะฟั€ะพะตะบั‚ะพะฒ +- quality gates + ะผะธะฝะธะผะฐะปัŒะฝั‹ะต ั‚ั€ะตะฑะพะฒะฐะฝะธั ะบ ั€ะตะทัƒะปัŒั‚ะฐั‚ัƒ +- cross-checks + ะฒะทะฐะธะผะฝั‹ะต ะฟั€ะพะฒะตั€ะบะธ ะผะตะถะดัƒ ั€ะพะปัะผะธ +- plan lock + ะทะฐะผะพั€ะพะทะบะฐ ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝะพะณะพ ะฟะปะฐะฝะฐ ะฟะพัะปะต approve +- ultra-mode + ัะฒะตั€ั…ัะบะพะฝะพะผะฝะฐั ั€ะฐะฑะพั‚ะฐ ั ะบะพะฝั‚ะตะบัั‚ะพะผ +- project DNA + ะบั€ะฐั‚ะบะฐั ะผะพะดะตะปัŒ ั…ะฐั€ะฐะบั‚ะตั€ะฐ ะฟั€ะพะดัƒะบั‚ะฐ ะธ ะตะณะพ ะพัะธ ัƒะฝะธะบะฐะปัŒะฝะพัั‚ะธ +- design profile + ัƒะฟั€ะฐะฒะปัะตะผะฐั ะผะพะดะตะปัŒ ะฒะธะทัƒะฐะปัŒะฝะพะน ัะผะตะปะพัั‚ะธ, ัะทั‹ะบะฐ ั„ะพั€ะผ ะธ ะธัั‚ะพั‡ะฝะธะบะพะฒ ัั‚ะธะปั +- anti-template rules + ะฟั€ะฐะฒะธะปะฐ ะฟั€ะพั‚ะธะฒ ัˆะฐะฑะปะพะฝะฝะพะน ะณะตะฝะตั€ะฐั†ะธะธ + +## ะ”ะปั ะบะพะณะพ ะพะฝ ะพัะพะฑะตะฝะฝะพ ะฟะพะปะตะทะตะฝ + +- ะดะปั ะฝะพะฒะธั‡ะบะพะฒ, ะบะพั‚ะพั€ั‹ะผ ัะปะพะถะฝะพ ัั€ะฐะทัƒ ะฟั€ะฐะฒะธะปัŒะฝะพ ัั„ะพั€ะผัƒะปะธั€ะพะฒะฐั‚ัŒ ะทะฐะดะฐั‡ัƒ ะ˜ะ˜ +- ะดะปั solo-ั€ะฐะทั€ะฐะฑะพั‚ั‡ะธะบะพะฒ, ะบะพั‚ะพั€ั‹ะผ ะฝัƒะถะฝะฐ ัั‚ั€ัƒะบั‚ัƒั€ะฐ ะฒะผะตัั‚ะพ ั…ะฐะพั‚ะธั‡ะฝะพะณะพ ะดะธะฐะปะพะณะฐ +- ะดะปั ั‚ะตั…, ะบั‚ะพ ั…ะพั‡ะตั‚ ะฒะตัั‚ะธ ะฟั€ะพะตะบั‚ ะฟะพ ัˆะฐะณะฐะผ, ะฐ ะฝะต โ€œะผะฐะณะธะตะนโ€ +- ะดะปั ั‚ะตั…, ะบะพะผัƒ ะฒะฐะถะฝะพ ะฝะต ั‚ะพะปัŒะบะพ ัะณะตะฝะตั€ะธั€ะพะฒะฐั‚ัŒ ะบะพะด, ะฝะพ ะธ ะฟะพะปัƒั‡ะธั‚ัŒ ะฝะพั€ะผะฐะปัŒะฝั‹ะน handoff + +## ะงั‚ะพ ัั‚ะพ ะฝะต ะดะตะปะฐะตั‚ + +ะŸะปะฐะณะธะฝ ะฝะต ะทะฐะผะตะฝัะตั‚ ะผั‹ัˆะปะตะฝะธะต ะธ ะฝะต ะฟั€ะตะฒั€ะฐั‰ะฐะตั‚ ะปัŽะฑัƒัŽ ะธะดะตัŽ ะฒ ะธะดะตะฐะปัŒะฝั‹ะน production-ะฟั€ะพะดัƒะบั‚ ะฟะพ ะพะดะฝะพะน ะบะฝะพะฟะบะต. + +ะžะฝ ะดะตะปะฐะตั‚ ะดั€ัƒะณะพะต: + +- ัะฝะธะถะฐะตั‚ ั…ะฐะพั +- ัƒะดะตั€ะถะธะฒะฐะตั‚ ัั‚ั€ัƒะบั‚ัƒั€ัƒ +- ะฝะต ะดะฐั‘ั‚ ะฟั€ะพะฟัƒัั‚ะธั‚ัŒ ะฒะฐะถะฝั‹ะต ัั‚ะฐะฟั‹ +- ะฟะพะผะพะณะฐะตั‚ ะดะพะฒะตัั‚ะธ ะฟั€ะพะตะบั‚ ะดะพ ะฑะพะปะตะต ะทั€ะตะปะพะณะพ ัะพัั‚ะพัะฝะธั + +ะขะพ ะตัั‚ัŒ ัั‚ะพ ะฝะต โ€œะฒะพะปัˆะตะฑะฝะฐั ะบะฝะพะฟะบะฐโ€, ะฐ ั…ะพั€ะพัˆะธะน ะพะฟะตั€ะฐั†ะธะพะฝะฝั‹ะน ัะปะพะน ะฝะฐะด Codex. + +## ะขะตะบัƒั‰ะตะต ัะพัั‚ะพัะฝะธะต + +ะกะตะนั‡ะฐั ะฟะปะฐะณะธะฝ ัƒะถะต ัƒะผะตะตั‚: + +- ั€ะฐะฑะพั‚ะฐั‚ัŒ ะฟะพ-ั€ัƒััะบะธ +- ะฒะตัั‚ะธ ะฟั€ะพะตะบั‚ ะฟะพ ั„ะฐะทะฐะผ +- ะฟะพะดะดะตั€ะถะธะฒะฐั‚ัŒ ะฝะตัะบะพะปัŒะบะพ ั‚ะธะฟะพะฒ ะฟั€ะพะตะบั‚ะพะฒ +- ั…ั€ะฐะฝะธั‚ัŒ ะปะพะบะฐะปัŒะฝัƒัŽ ะฟะฐะผัั‚ัŒ ะฟั€ะพะตะบั‚ะฐ +- ัƒั‡ะธั‚ั‹ะฒะฐั‚ัŒ ะฒั‚ะพั€ะธั‡ะฝั‹ะต ะฐั€ั…ะตั‚ะธะฟั‹ ะธ capabilities +- ะฒะตัั‚ะธ discovery ะฒ ะดะฒะต ะฒะพะปะฝั‹ ะธ ัะพะฑะธั€ะฐั‚ัŒ ะฑะพะปะตะต ัะธะปัŒะฝั‹ะน brief +- ั€ะฐะทะปะธั‡ะฐั‚ัŒ ัะฟะพะบะพะนะฝั‹ะน, ะฒั‹ั€ะฐะทะธั‚ะตะปัŒะฝั‹ะน ะธ ัะผะตะปั‹ะน ะดะธะทะฐะนะฝ +- ัƒั‡ะธั‚ั‹ะฒะฐั‚ัŒ ะปะพะบะฐะปัŒะฝั‹ะต style-skills, brand guide, moodboard ะธ `design-system.json` +- ั‚ั€ะตะฑะพะฒะฐั‚ัŒ ะบะธั€ะธะปะปะธั‡ะตัะบะธ ัะพะฒะผะตัั‚ะธะผั‹ะต ัˆั€ะธั„ั‚ั‹ ะดะปั ั€ัƒััะบะพะณะพ ะธะฝั‚ะตั€ั„ะตะนัะฐ +- ะถั‘ัั‚ั‡ะต ะฟั€ะพะฒะตั€ัั‚ัŒ mobile, ะฐะดะฐะฟั‚ะธะฒ ะธ ั‡ะธั‚ะฐะตะผะพัั‚ัŒ +- ะทะฐะผะพั€ะฐะถะธะฒะฐั‚ัŒ ะฟะปะฐะฝ ะฟะพัะปะต approve +- ัะบะพะฝะพะผะธั‚ัŒ ั‚ะพะบะตะฝั‹ ั‡ะตั€ะตะท phase-card, ultra-context ะธ ั„ะฐะทะพะฒั‹ะน context bundle +- ะฒะฐะปะธะดะธั€ะพะฒะฐั‚ัŒ ัะพัั‚ะพัะฝะธะต ะฟั€ะพะตะบั‚ะฐ ะฟะตั€ะตะด handoff + +## ะฃัั‚ะฐะฝะพะฒะบะฐ + +ะญั‚ะพั‚ ั€ะตะฟะพะทะธั‚ะพั€ะธะน ะธ ะตัั‚ัŒ ะฟะปะฐะณะธะฝ. + +ะ•ะณะพ ะผะพะถะฝะพ ะฟะพะดะบะปัŽั‡ะฐั‚ัŒ ะดะฒัƒะผั ัะฟะพัะพะฑะฐะผะธ: + +- ะบะฐะบ ะพะฑั‰ะธะน ะปะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ ะดะปั ะฒัะตั… ะฟั€ะพะตะบั‚ะพะฒ +- ะบะฐะบ ะปะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ ะฒะฝัƒั‚ั€ะธ ะบะพะฝะบั€ะตั‚ะฝะพะณะพ ะฟั€ะพะตะบั‚ะฐ + +ะžัะฝะพะฒะฝะพะน ั€ะตะบะพะผะตะฝะดัƒะตะผั‹ะน ัั†ะตะฝะฐั€ะธะน: ัƒัั‚ะฐะฝะพะฒะธั‚ัŒ ะตะณะพ ะพะดะธะฝ ั€ะฐะท ะบะฐะบ **ะพะฑั‰ะธะน ะปะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ** ะธ ะดะฐะปัŒัˆะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒ ะปัŽะฑั‹ั… ะฟั€ะพะตะบั‚ะฐั…. + +ะŸั€ะธ ัั‚ะพะผ: + +- ัะฐะผ ะฟะปะฐะณะธะฝ ั…ั€ะฐะฝะธั‚ัั ะพะดะธะฝ ั€ะฐะท +- ะฒ ะบะฐะถะดะพะผ ะฝะพะฒะพะผ ะฟั€ะพะตะบั‚ะต ัะพะทะดะฐัŽั‚ัั ัะฒะพะธ ะปะพะบะฐะปัŒะฝั‹ะต `.codex-agent` ั„ะฐะนะปั‹ +- ะฟั€ะพะตะบั‚ั‹ ะฝะต ะผะตัˆะฐัŽั‚ ะดั€ัƒะณ ะดั€ัƒะณัƒ + +### ะกะฐะผั‹ะน ะฟั€ะพัั‚ะพะน ัะฟะพัะพะฑ + +ะœะพะถะฝะพ ะฒะพะพะฑั‰ะต ะฝะต ะฝะฐัั‚ั€ะฐะธะฒะฐั‚ัŒ ะฒัั‘ ั€ัƒะบะฐะผะธ. + +ะ”ะพัั‚ะฐั‚ะพั‡ะฝะพ ะดะฐั‚ัŒ Codex ััั‹ะปะบัƒ ะฝะฐ ัั‚ะพั‚ GitHub-ั€ะตะฟะพะทะธั‚ะพั€ะธะน ะธ ะฝะฐะฟะธัะฐั‚ัŒ ั‡ั‚ะพ-ั‚ะพ ะฒั€ะพะดะต: + +```text +ะกะบะปะพะฝะธั€ัƒะน ัั‚ะพั‚ ั€ะตะฟะพะทะธั‚ะพั€ะธะน ะธ ัƒัั‚ะฐะฝะพะฒะธ ะฟะปะฐะณะธะฝ ะณะปะพะฑะฐะปัŒะฝะพ, ั‡ั‚ะพะฑั‹ ะพะฝ ะฑั‹ะป ะดะพัั‚ัƒะฟะตะฝ ะฒะพ ะฒัะตั… ะฟั€ะพะตะบั‚ะฐั…. +``` + +ะŸะพัะปะต ัั‚ะพะณะพ Codex ะผะพะถะตั‚: + +1. ัะบะฐั‡ะฐั‚ัŒ ั€ะตะฟะพะทะธั‚ะพั€ะธะน +2. ัะฐะผ ะฟั€ะพะฟะธัะฐั‚ัŒ `marketplace.json` +3. ะฟะพะดะบะปัŽั‡ะธั‚ัŒ ะปะพะบะฐะปัŒะฝั‹ะน ะฟัƒั‚ัŒ ะบ ะฟะปะฐะณะธะฝัƒ + +ะขะพะณะดะฐ ะฒะฐะผ ะพัั‚ะฐะฝะตั‚ัั ั‚ะพะปัŒะบะพ: + +1. ะพั‚ะบั€ั‹ั‚ัŒ `Skills & Apps` +2. ะฝะฐะนั‚ะธ `Codex Project Autopilot` +3. ะฝะฐะถะฐั‚ัŒ `Install` + +ะ”ะปั ะณะปะพะฑะฐะปัŒะฝะพะน ัƒัั‚ะฐะฝะพะฒะบะธ ะฒ ั€ะตะฟะพะทะธั‚ะพั€ะธะธ ะตัั‚ัŒ ะฐะฒั‚ะพัƒัั‚ะฐะฝะพะฒั‰ะธะบ: + +```bash +python3 scripts/install_home_plugin.py +``` + +ะžะฝ ัะฐะผ: + +1. ัะบะพะฟะธั€ัƒะตั‚ ะฟะปะฐะณะธะฝ ะฒ `~/plugins/codex-project-autopilot` +2. ัะพะทะดะฐัั‚ ะธะปะธ ะพะฑะฝะพะฒะธั‚ `~/.agents/plugins/marketplace.json` +3. ะทะฐั€ะตะณะธัั‚ั€ะธั€ัƒะตั‚ ะฟะปะฐะณะธะฝ ะบะฐะบ ะพะฑั‰ะธะน ะปะพะบะฐะปัŒะฝั‹ะน ะธัั‚ะพั‡ะฝะธะบ ะดะปั Codex + +### 1. ะกะบะฐั‡ะฐะนั‚ะต ัั‚ะพั‚ ั€ะตะฟะพะทะธั‚ะพั€ะธะน + +ะกะบะปะพะฝะธั€ัƒะนั‚ะต ั€ะตะฟะพะทะธั‚ะพั€ะธะน ะธะปะธ ัะบะฐั‡ะฐะนั‚ะต ะฐั€ั…ะธะฒ ั GitHub. + +ะ”ะฐะปัŒัˆะต ะฒั‹ะฑะตั€ะธั‚ะต ะพะดะธะฝ ะธะท ะดะฒัƒั… ะฒะฐั€ะธะฐะฝั‚ะพะฒ. + +#### ะ’ะฐั€ะธะฐะฝั‚ A. ะ“ะปะพะฑะฐะปัŒะฝะฐั ัƒัั‚ะฐะฝะพะฒะบะฐ ะดะปั ะฒัะตั… ะฟั€ะพะตะบั‚ะพะฒ + +ะญั‚ะพ ะพัะฝะพะฒะฝะพะน ั€ะตะบะพะผะตะฝะดัƒะตะผั‹ะน ะฒะฐั€ะธะฐะฝั‚. + +ะŸั€ะพัั‚ะพ ะทะฐะฟัƒัั‚ะธั‚ะต: + +```bash +python3 scripts/install_home_plugin.py +``` + +ะŸะพัะปะต ัั‚ะพะณะพ ะฟะปะฐะณะธะฝ ะฑัƒะดะตั‚ ะทะฐั€ะตะณะธัั‚ั€ะธั€ะพะฒะฐะฝ ะบะฐะบ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะธะน ะปะพะบะฐะปัŒะฝั‹ะน ะฟะปะฐะณะธะฝ. + +ะคะฐะนะปั‹ ัƒัั‚ะฐะฝะพะฒะบะธ ะฑัƒะดัƒั‚ ะปะตะถะฐั‚ัŒ ั‚ะฐะบ: + +```text +~/ +โ”œโ”€โ”€ .agents/ +โ”‚ โ””โ”€โ”€ plugins/ +โ”‚ โ””โ”€โ”€ marketplace.json +โ””โ”€โ”€ plugins/ + โ””โ”€โ”€ codex-project-autopilot/ +``` + +ะ“ะพั‚ะพะฒั‹ะน ะฟั€ะธะผะตั€ ะดะปั ัั‚ะพะณะพ ั€ะตะถะธะผะฐ ะปะตะถะธั‚ ะฒ [examples/home-marketplace.json](/Users/a/tgbot/codex-project-autopilot/examples/home-marketplace.json). + +ะŸะพัะปะต ั‚ะฐะบะพะน ัƒัั‚ะฐะฝะพะฒะบะธ: + +- ะพั‚ะบั€ั‹ะฒะฐะตั‚ะต ะปัŽะฑะพะน ะฟั€ะพะตะบั‚ ะฒ Codex +- ะทะฐั…ะพะดะธั‚ะต ะฒ `Skills & Apps` +- ะฟะตั€ะตะบะปัŽั‡ะฐะตั‚ะตััŒ ะฝะฐ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะธะน ะธัั‚ะพั‡ะฝะธะบ +- ะฝะฐะถะธะผะฐะตั‚ะต `Install` ัƒ `Codex Project Autopilot` + +ะกะฐะผ `.codex-agent` ะฟั€ะธ ัั‚ะพะผ ะฒัั‘ ั€ะฐะฒะฝะพ ะฑัƒะดะตั‚ ัะพะทะดะฐะฒะฐั‚ัŒัั ัƒะถะต ะฒ ั‚ะตะบัƒั‰ะตะผ ะฟั€ะพะตะบั‚ะต, ะณะดะต ะฒั‹ ั€ะตะฐะปัŒะฝะพ ั€ะฐะฑะพั‚ะฐะตั‚ะต. + +#### ะ’ะฐั€ะธะฐะฝั‚ B. ะŸะปะฐะณะธะฝ ะปะตะถะธั‚ ะฒะฝัƒั‚ั€ะธ ะฟั€ะพะตะบั‚ะฐ + +ะŸะพะปะพะถะธั‚ะต ั€ะตะฟะพะทะธั‚ะพั€ะธะน ััŽะดะฐ: + +`plugins/autonomous-project-agent/` + +ะ˜ั‚ะพะณะพะฒะฐั ัั‚ั€ัƒะบั‚ัƒั€ะฐ ะดะพะปะถะฝะฐ ะฒั‹ะณะปัะดะตั‚ัŒ ั‚ะฐะบ: + +```text +ะฒะฐัˆ-ะฟั€ะพะตะบั‚/ +โ”œโ”€โ”€ .agents/ +โ”œโ”€โ”€ plugins/ +โ”‚ โ””โ”€โ”€ autonomous-project-agent/ +โ””โ”€โ”€ ... +``` + +### 2. ะ”ะพะฑะฐะฒัŒั‚ะต ะปะพะบะฐะปัŒะฝั‹ะน marketplace + +ะ”ะปั project-local ั€ะตะถะธะผะฐ ะฒ ะฟั€ะพะตะบั‚ะต ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ั„ะฐะนะป: + +`.agents/plugins/marketplace.json` + +ะ•ัะปะธ ั„ะฐะนะปะฐ ะตั‰ั‘ ะฝะตั‚, ัะพะทะดะฐะนั‚ะต ะตะณะพ. ะ•ัะปะธ ะพะฝ ัƒะถะต ะตัั‚ัŒ, ะดะพะฑะฐะฒัŒั‚ะต ะฒ ะฝะตะณะพ ะทะฐะฟะธััŒ ะดะปั ะปะพะบะฐะปัŒะฝะพะณะพ ะฟะปะฐะณะธะฝะฐ. + +ะ“ะพั‚ะพะฒั‹ะน ะฟั€ะธะผะตั€ ั‚ะฐะบะถะต ะปะตะถะธั‚ ะฒ [examples/marketplace.json](/Users/a/tgbot/codex-project-autopilot/examples/marketplace.json). + +ะ•ัะปะธ ะฝะต ั…ะพั‚ะธั‚ะต ั€ะตะดะฐะบั‚ะธั€ะพะฒะฐั‚ัŒ JSON ะฒั€ัƒั‡ะฝัƒัŽ, ะฟั€ะพัั‚ะพ ะทะฐะฟัƒัั‚ะธั‚ะต: + +```bash +python3 scripts/install_local_plugin.py --workspace . +``` + +ะกะบั€ะธะฟั‚ ัะฐะผ ัะพะทะดะฐัั‚ ะธะปะธ ะพะฑะฝะพะฒะธั‚ `marketplace.json`. + +ะœะธะฝะธะผะฐะปัŒะฝั‹ะน ะฟั€ะธะผะตั€ ะดะปั ะฒะฐั€ะธะฐะฝั‚ะฐ B: + +```json +{ + "name": "morecil-local", + "interface": { + "displayName": "Morecil Local Plugins" + }, + "plugins": [ + { + "name": "codex-project-autopilot", + "source": { + "source": "local", + "path": "./plugins/autonomous-project-agent" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} +``` + +ะ˜ะผะตะฝะฝะพ ัั‚ะพั‚ ั„ะฐะนะป ะดะตะปะฐะตั‚ ะฟะปะฐะณะธะฝ ะฒะธะดะธะผั‹ะผ ะฒ `Skills & Apps`. + +ะ•ัะปะธ ะฒ ะธะฝั‚ะตั€ั„ะตะนัะต Codex ั€ัะดะพะผ ั ะบะฐั‚ะตะณะพั€ะธะตะน ะฒั‹ ะฒะธะดะธั‚ะต ั‡ั‚ะพ-ั‚ะพ ะฒั€ะพะดะต `morecil-local, Productivity`, ัั‚ะพ ะพะทะฝะฐั‡ะฐะตั‚: + +- `Productivity` โ€” ะบะฐั‚ะตะณะพั€ะธั ัะฐะผะพะณะพ ะฟะปะฐะณะธะฝะฐ +- `morecil-local` โ€” ะธะผั ะปะพะบะฐะปัŒะฝะพะณะพ marketplace-ะธัั‚ะพั‡ะฝะธะบะฐ + +ะขะพ ะตัั‚ัŒ ัั‚ะพ ะฝะต ะดะฒะต ะบะฐั‚ะตะณะพั€ะธะธ, ะฐ `ะธัั‚ะพั‡ะฝะธะบ + ะบะฐั‚ะตะณะพั€ะธั`. + +### 3. ะŸั€ะพะฒะตั€ัŒั‚ะต Python + +ะ”ะปั ะปะพะบะฐะปัŒะฝั‹ั… ัะบั€ะธะฟั‚ะพะฒ ะฟะปะฐะณะธะฝัƒ ะฝัƒะถะตะฝ ัƒัั‚ะฐะฝะพะฒะปะตะฝะฝั‹ะน Python 3. + +ะญั‚ะพ ะฒะฐะถะฝะพ ะดะปั: + +- ะธะฝะธั†ะธะฐะปะธะทะฐั†ะธะธ `.codex-agent` +- ะปะพะบะฐะปัŒะฝะพะน ะฒะฐะปะธะดะฐั†ะธะธ ัะพัั‚ะพัะฝะธั +- guardrail-ะฟั€ะพะฒะตั€ะพะบ ะฟะพัะปะต ะทะฐะฟะธัะธ ั„ะฐะนะปะพะฒ + +### 4. ะฃัั‚ะฐะฝะพะฒะธั‚ะต ะฟะปะฐะณะธะฝ ะฒ Codex + +ะŸะพัะปะต ัั‚ะพะณะพ: + +- ะพั‚ะบั€ะพะนั‚ะต ะฟั€ะพะตะบั‚ ะฒ Codex +- ะทะฐะนะดะธั‚ะต ะฒ `Skills & Apps` +- ะฒ ั„ะธะปัŒั‚ั€ะต ะธัั‚ะพั‡ะฝะธะบะพะฒ ะฒั‹ะฑะตั€ะธั‚ะต ะฝัƒะถะฝั‹ะน ะธัั‚ะพั‡ะฝะธะบ: + - `ะŸะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะธะน` ะดะปั ะณะปะพะฑะฐะปัŒะฝะพะน ัƒัั‚ะฐะฝะพะฒะบะธ + - ะปะพะบะฐะปัŒะฝั‹ะน marketplace ะฟั€ะพะตะบั‚ะฐ ะดะปั project-local ั€ะตะถะธะผะฐ +- ะฝะฐะนะดะธั‚ะต `Codex Project Autopilot` +- ะฝะฐะถะผะธั‚ะต `Install` + +ะŸะพัะปะต ัƒัั‚ะฐะฝะพะฒะบะธ ะฟะปะฐะณะธะฝ ัั‚ะฐะฝะตั‚ ะดะพัั‚ัƒะฟะตะฝ ะฒ Codex ะดะปั ัั‚ะพะณะพ ะธัั‚ะพั‡ะฝะธะบะฐ. ะกะฐะผะพ ัะพัั‚ะพัะฝะธะต `.codex-agent` ะฑัƒะดะตั‚ ัะพะทะดะฐะฒะฐั‚ัŒัั ัƒะถะต ะฒ ั‚ะพะน ะฟะฐะฟะบะต ะฟั€ะพะตะบั‚ะฐ, ะณะดะต ะฒั‹ ั€ะตะฐะปัŒะฝะพ ะตะณะพ ะธัะฟะพะปัŒะทัƒะตั‚ะต. + +### ะ‘ั‹ัั‚ั€ั‹ะน ัั†ะตะฝะฐั€ะธะน + +1. ะกะบะฐั‡ะฐะนั‚ะต ัั‚ะพั‚ ั€ะตะฟะพะทะธั‚ะพั€ะธะน. +2. ะ—ะฐะฟัƒัั‚ะธั‚ะต `python3 scripts/install_home_plugin.py`. +3. ะžั‚ะบั€ะพะนั‚ะต ะปัŽะฑะพะน ะฟั€ะพะตะบั‚ ะฒ Codex. +4. ะžั‚ะบั€ะพะนั‚ะต ะฟั€ะพะตะบั‚ ะฒ Codex. +5. ะ—ะฐะนะดะธั‚ะต ะฒ `Skills & Apps`. +6. ะ’ั‹ะฑะตั€ะธั‚ะต ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะธะน ะธัั‚ะพั‡ะฝะธะบ ะฟะปะฐะณะธะฝะพะฒ. +7. ะะฐะถะผะธั‚ะต `Install` ัƒ `Codex Project Autopilot`. + +### 5. ะะฐั‡ะฝะธั‚ะต ั€ะฐะฑะพั‚ัƒ + +ะŸะพัะปะต ัƒัั‚ะฐะฝะพะฒะบะธ ะฟะปะฐะณะธะฝ ะผะพะถะฝะพ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะดะปั: + +- ะทะฐะฟัƒัะบะฐ ะฝะพะฒะพะณะพ ะฟั€ะพะตะบั‚ะฐ ะธะท ะธะดะตะธ +- ะฟั€ะพะดะพะปะถะตะฝะธั ัƒะถะต ะฝะฐั‡ะฐั‚ะพะณะพ ะฟั€ะพะตะบั‚ะฐ +- ะฟะพะดะณะพั‚ะพะฒะบะธ ะดะตะฟะปะพั ะธ ัะตะบั€ะตั‚ะพะฒ +- ะพะฑัŠััะฝะตะฝะธั ั‚ะตะบัƒั‰ะตะณะพ ะฟั€ะพะตะบั‚ะฐ ะฟั€ะพัั‚ั‹ะผ ัะทั‹ะบะพะผ + +### ะ’ะฐะถะฝะพ + +- ะ›ัƒั‡ัˆะธะน ั€ะตะถะธะผ ะดะปั ะฟะพะฒัะตะดะฝะตะฒะฝะพะน ั€ะฐะฑะพั‚ั‹ โ€” ะณะปะพะฑะฐะปัŒะฝะฐั ัƒัั‚ะฐะฝะพะฒะบะฐ ั‡ะตั€ะตะท `install_home_plugin.py`. +- ะ’ ัั‚ะพะผ ั€ะตะถะธะผะต ะพะดะธะฝ ะธ ั‚ะพั‚ ะถะต ะฟะปะฐะณะธะฝ ะดะพัั‚ัƒะฟะตะฝ ะฒ ะปัŽะฑั‹ั… ะฟั€ะพะตะบั‚ะฐั…. +- ะ•ัะปะธ ะฒั‹ ะธัะฟะพะปัŒะทัƒะตั‚ะต project-local ัƒัั‚ะฐะฝะพะฒะบัƒ, ั‚ะพะณะดะฐ ะดะฐ: ะฟะฐะฟะบัƒ ะฟะปะฐะณะธะฝะฐ ะธ `marketplace.json` ะฝัƒะถะฝะพ ะดะพะฑะฐะฒะธั‚ัŒ ะฒ ะบะพะฝะบั€ะตั‚ะฝั‹ะน ะฟั€ะพะตะบั‚. +- `.codex-agent` ะฝะต ัะฒะปัะตั‚ัั ั‡ะฐัั‚ัŒัŽ ัะฐะผะพะณะพ ะฟะปะฐะณะธะฝะฐ. ะญั‚ะฐ ะฟะฐะฟะบะฐ ัะพะทะดะฐั‘ั‚ัั ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace, ะณะดะต ะฒั‹ ะทะฐะฟัƒัะบะฐะตั‚ะต ะฟะปะฐะณะธะฝ. + +## ะšัƒะดะฐ ั€ะฐะทะฒะธะฒะฐั‚ัŒ ะดะฐะปัŒัˆะต + +ะกะปะตะดัƒัŽั‰ะธะต ัะธะปัŒะฝั‹ะต ะฝะฐะฟั€ะฐะฒะปะตะฝะธั ะดะปั ั€ะฐะทะฒะธั‚ะธั: + +- ะตั‰ั‘ ะฑะพะปะตะต ัƒะผะฝั‹ะต role contracts +- ั€ะฐััˆะธั€ะตะฝะฝะฐั ะฟะพะดะดะตั€ะถะบะฐ ัะผะตัˆะฐะฝะฝั‹ั… ะฟั€ะพะตะบั‚ะพะฒ +- ะฑะพะปะตะต ัั‚ั€ะพะณะธะต phase transitions +- ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะพะต ะพะฑะฝะพะฒะปะตะฝะธะต scorecard ะธ verification report +- ะตั‰ั‘ ะฑะพะปะตะต ะฐะณั€ะตััะธะฒะฝะฐั ัะบะพะฝะพะผะธั ั‚ะพะบะตะฝะพะฒ ะฝะฐ ะดะปะธะฝะฝั‹ั… ะฟั€ะพะตะบั‚ะฐั… +- ะฑะพะปะตะต ะณะปัƒะฑะพะบะธะต product/design heuristics ะดะปั ะฝะตั‚ะธะฟะพะฒั‹ั… ะทะฐะดะฐั‡ + +## ะ˜ั‚ะพะณ + +Codex Project Autopilot ะฝัƒะถะตะฝ ะดะปั ั‚ะพะณะพ, ั‡ั‚ะพะฑั‹ Codex ั€ะฐะฑะพั‚ะฐะป ะฝะต ะบะฐะบ ะณะตะฝะตั€ะฐั‚ะพั€ ัะปัƒั‡ะฐะนะฝั‹ั… ะพั‚ะฒะตั‚ะพะฒ, ะฐ ะบะฐะบ ัƒะฟั€ะฐะฒะปัะตะผะฐั ะผะธะฝะธ-ะบะพะผะฐะฝะดะฐ ั ะฟะฐะผัั‚ัŒัŽ, ัั‚ะฐะฟะฐะผะธ, ะฟั€ะพะฒะตั€ะบะฐะผะธ ะธ ั„ะธะฝะฐะปัŒะฝะพะน ะฟะตั€ะตะดะฐั‡ะตะน ะฟั€ะพะตะบั‚ะฐ. + +ะ•ัะปะธ ะบะพั€ะพั‚ะบะพ: +ะธะดะตั -> ะฒะพะฟั€ะพัั‹ -> ะฟะปะฐะฝ -> ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะธะต -> ั€ะตะฐะปะธะทะฐั†ะธั -> ะฟั€ะพะฒะตั€ะบะฐ -> handoff + +## ะŸั€ะพะฒะตั€ะบะฐ ะปะพะบะฐะปัŒะฝะพ + +ะ•ัะปะธ ั…ะพั‚ะธั‚ะต ะฑั‹ัั‚ั€ะพ ะฟั€ะพะฒะตั€ะธั‚ัŒ, ั‡ั‚ะพ ะฟะปะฐะณะธะฝ ะฝะต ะฟะพะฒั€ะตะถะดั‘ะฝ ะฟะพัะปะต ัะบะฐั‡ะธะฒะฐะฝะธั: + +```bash +python3 -m py_compile scripts/*.py tests/*.py +python3 -m unittest discover -s tests +``` diff --git a/plugins/AlexMi64/codex-project-autopilot/assets/autonomous-project-agent.svg b/plugins/AlexMi64/codex-project-autopilot/assets/autonomous-project-agent.svg new file mode 100644 index 0000000..b8abb8f --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/assets/autonomous-project-agent.svg @@ -0,0 +1,11 @@ + + Autonomous Project Agent + + + + + + + + + diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/automation-builder/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/automation-builder/SKILL.md new file mode 100644 index 0000000..fd210d6 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/automation-builder/SKILL.md @@ -0,0 +1,58 @@ +--- +name: automation-builder +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะดะปั automation-ะทะฐะดะฐั‡ ะฟะพ ะตะณะพ ะฟะปะฐะฝัƒ; ะฝะต ะฒะบะปัŽั‡ะฐะน ะดะปั ะพะฑั‹ั‡ะฝั‹ั… ัะบั€ะธะฟั‚ะพะฒ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะ˜ะฝะถะตะฝะตั€ ะฐะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธะน + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะ•ัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟั€ะพัั‚ะพ ะฟั€ะพัะธั‚ ะฝะฐะฟะธัะฐั‚ัŒ ัะบั€ะธะฟั‚ ะธ ะฝะต ะทะฐะฟัƒัะบะฐะป ะฐะฒั‚ะพะฟะธะปะพั‚, ัั‚ะพั‚ skill ะฝะต ะดะพะปะถะตะฝ ะฟะพะดั…ะฒะฐั‚ั‹ะฒะฐั‚ัŒัั ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ะผะฐะปะตะฝัŒะบะธะต, ะฝะพ ะฝะฐะดะตะถะฝั‹ะต ะฐะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธะธ. + +## ะ’ั…ะพะด + +- `implementation-plan.md` +- `tech-context.md` +- `active-context.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- ะบะพะด automation-ัะบั€ะธะฟั‚ะฐ ะธะปะธ worker +- `execution-log.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ะดะตะปะฐั‚ัŒ ะผะธะฝะธะผะฐะปัŒะฝั‹ะน ะฟะพะปะตะทะฝั‹ะน happy path +- ะดะพะฑะฐะฒะปัั‚ัŒ dry-run, ะตัะปะธ ะตัั‚ัŒ side effects +- ะปะพะณะธั€ะพะฒะฐั‚ัŒ ะฒั…ะพะดั‹, ะดะตะนัั‚ะฒะธั ะธ ัะฑะพะธ +- ะฟั€ะพะดัƒะผั‹ะฒะฐั‚ัŒ retry ั‚ะพะปัŒะบะพ ั‚ะฐะผ, ะณะดะต ะตัั‚ัŒ ะฒะฝะตัˆะฝะธะน I/O + +## Automation-ะฟะพะดั…ะพะด Morecil + +ะะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธั ะดะพะปะถะฝะฐ ะฑั‹ั‚ัŒ ะฟั€ะตะดัะบะฐะทัƒะตะผะพะน. + +ะ•ัะปะธ ะฟะพัะปะต ะทะฐะฟัƒัะบะฐ ะฝะตะปัŒะทั ะฟะพะฝัั‚ัŒ, ั‡ั‚ะพ ะพะฝะฐ ัะดะตะปะฐะปะฐ, ะทะฝะฐั‡ะธั‚ ั€ะฐะฑะพั‚ะฐ ะฝะตะดะพะฒะตะดะตะฝะฐ. + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะดะตะปะฐั‚ัŒ automation โ€œั‡ะตั€ะฝั‹ะผ ัั‰ะธะบะพะผโ€ +- ะฟะธัะฐั‚ัŒ ัะบั€ะธะฟั‚ ะฑะตะท ะปะพะณะพะฒ +- ะดะพะฑะฐะฒะปัั‚ัŒ ะฑะฐะทัƒ ะฑะตะท ัะฒะฝะพะน ะฝัƒะถะดั‹ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะตัั‚ัŒ ะปะธ safe preview? +- ะผะพะถะฝะพ ะปะธ ะฟะพะฝัั‚ัŒ ัะฑะพะน ะฟะพ ะปะพะณะฐะผ? +- ะฝะต ะดัƒะฑะปะธั€ัƒะตั‚ ะปะธ ะฟะพะฒั‚ะพั€ะฝั‹ะน ะทะฐะฟัƒัะบ ะฟะพะฑะพั‡ะฝั‹ะต ัั„ั„ะตะบั‚ั‹? + +## Handoff ะดะฐะปัŒัˆะต + +ะŸะตั€ะตะดะฐะน: + +- ั‡ั‚ะพ ะดะตะปะฐะตั‚ dry-run +- ะณะดะต ัะผะพั‚ั€ะตั‚ัŒ ะปะพะณะธ +- ะบะฐะบะธะต side effects ะพัั‚ะฐัŽั‚ัั ะพะฟะฐัะฝั‹ะผะธ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/autonomous-project-orchestrator/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/autonomous-project-orchestrator/SKILL.md new file mode 100644 index 0000000..253708c --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/autonomous-project-orchestrator/SKILL.md @@ -0,0 +1,202 @@ +--- +name: autonomous-project-orchestrator +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะบะพะณะดะฐ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ัะฒะฝะพ ะฟั€ะพัะธั‚ ะทะฐะฟัƒัั‚ะธั‚ัŒ Codex Project Autopilot, ะฟั€ะพะดะพะปะถะธั‚ัŒ ะฟั€ะพะตะบั‚ ะธะท .codex-agent ะธะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ัƒะถะต ะตัั‚ัŒ ะฐะบั‚ะธะฒะฝั‹ะน .codex-agent. +--- + +# ะะฒั‚ะพะฝะพะผะฝั‹ะน ะžั€ะบะตัั‚ั€ะฐั‚ะพั€ ะŸั€ะพะตะบั‚ะฐ + +ะญั‚ะพ ะณะปะฐะฒะฝะฐั ั€ะพะปัŒ ะฟะปะฐะณะธะฝะฐ. ะžะฝะฐ ะฝะต ะฟะธัˆะตั‚ ะฒะตััŒ ะบะพะด ัะฐะผะฐ, ะฐ ัƒะฟั€ะฐะฒะปัะตั‚ ะพัั‚ะฐะปัŒะฝั‹ะผะธ ั€ะพะปัะผะธ ะบะฐะบ ะผะฐะปะตะฝัŒะบะพะน ะบะพะผะฐะฝะดะพะน. + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฐะบั‚ะธะฒะธั€ัƒะน ัั‚ะพั‚ skill ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ ั‚ะพะปัŒะบะพ ะฟะพั‚ะพะผัƒ, ั‡ั‚ะพ ะทะฐะดะฐั‡ะฐ ะฟะพั…ะพะถะฐ ะฝะฐ ะฟะปะฐะฝะธั€ะพะฒะฐะฝะธะต, frontend, backend ะธะปะธ ะดะธะทะฐะนะฝ. + +ะญั‚ะพั‚ skill ะฒะบะปัŽั‡ะฐะตั‚ัั ั‚ะพะปัŒะบะพ ะตัะปะธ ะฒั‹ะฟะพะปะฝะตะฝะพ ะพะดะฝะพ ะธะท ัƒัะปะพะฒะธะน: + +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ัะฒะฝะพ ะฟั€ะพัะธั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ `Codex Project Autopilot` +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟั€ะพัะธั‚ ะทะฐะฟัƒัั‚ะธั‚ัŒ ะฝะพะฒั‹ะน ะฟั€ะพะตะบั‚ ั‡ะตั€ะตะท ะฐะฒั‚ะพะฟะธะปะพั‚ +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟั€ะพัะธั‚ ะฟั€ะพะดะพะปะถะธั‚ัŒ ะฟั€ะพะตะบั‚ ะธะท `.codex-agent` +- ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ัƒะถะต ะตัั‚ัŒ ะฐะบั‚ะธะฒะฝั‹ะน `.codex-agent`, ะธ ะทะฐะดะฐั‡ะฐ ัะฒะฝะพ ะพั‚ะฝะพัะธั‚ัั ะบ ะตะณะพ ั‚ะตะบัƒั‰ะตะน ั„ะฐะทะต + +## ะกะธัั‚ะตะผะฐ Morecil + +ะขั‹ ั€ะฐะฑะพั‚ะฐะตัˆัŒ ะฟะพ ะฒะฝัƒั‚ั€ะตะฝะฝะตะน ัะธัั‚ะตะผะต `Morecil Role System`. + +ะญั‚ะพ ะทะฝะฐั‡ะธั‚: + +- ะบะฐะถะดะฐั ั€ะพะปัŒ ะธะผะตะตั‚ ัะฒะพะน ะบะพะฝั‚ั€ะฐะบั‚ +- ะบะฐะถะดะฐั ั€ะพะปัŒ ะพะฑัะทะฐะฝะฐ ะพั‚ะดะฐั‚ัŒ ะบะพะฝะบั€ะตั‚ะฝั‹ะต ะฐั€ั‚ะตั„ะฐะบั‚ั‹ +- handoff ะผะตะถะดัƒ ั€ะพะปัะผะธ ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ะบะพั€ะพั‚ะบะธะผ ะธ ัะฒะฝั‹ะผ +- ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ ะฝะต ะดะฒะธะณะฐะตั‚ ั€ะฐะฑะพั‚ัƒ ะดะฐะปัŒัˆะต, ะตัะปะธ ะบะพะฝั‚ั€ะฐะบั‚ ั€ะพะปะธ ะฝะต ะฒั‹ะฟะพะปะฝะตะฝ + +## ะงั‚ะพ ะดะตะปะฐะตั‚ + +- ะฟั€ะธะฝะธะผะฐะตั‚ ะธะดะตัŽ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั +- ะตัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, ัะฝะฐั‡ะฐะปะฐ ัะพะทะดะฐะตั‚ ะปะพะบะฐะปัŒะฝะพะต ัะพัั‚ะพัะฝะธะต ะฟั€ะพะตะบั‚ะฐ +- ะทะฐะฟัƒัะบะฐะตั‚ ะบะฒะธะท ะฟั€ะพัั‚ั‹ะผะธ ะฒะพะฟั€ะพัะฐะผะธ +- ะฟะพัะปะต ะฟะตั€ะฒะพะน ะฒะพะปะฝั‹ ะพั‚ะฒะตั‚ะพะฒ ะทะฐะฟัƒัะบะฐะตั‚ ะบะพั€ะพั‚ะบัƒัŽ ะฒะพะปะฝัƒ ัƒั‚ะพั‡ะฝััŽั‰ะธั… ะฒะพะฟั€ะพัะพะฒ, ะตัะปะธ ะดะฐะฝะฝั‹ั… ะตั‰ั‘ ะฝะตะดะพัั‚ะฐั‚ะพั‡ะฝะพ +- ั„ะธะบัะธั€ัƒะตั‚, ั‡ั‚ะพ ะดะตะปะฐะตั‚ ัั‚ะพั‚ ะฟั€ะพะตะบั‚ ัƒะฝะธะบะฐะปัŒะฝั‹ะผ ะธ ั‡ะตะณะพ ะฒ ะฝั‘ะผ ะฝะตะปัŒะทั ะดะตะปะฐั‚ัŒ ะฟะพ ัˆะฐะฑะปะพะฝัƒ +- ะพะฟั€ะตะดะตะปัะตั‚ ะฐั€ั…ะตั‚ะธะฟ ะฟั€ะพะตะบั‚ะฐ +- ะพะฟั€ะตะดะตะปัะตั‚ ะฒั‚ะพั€ะธั‡ะฝั‹ะต ะฐั€ั…ะตั‚ะธะฟั‹ ะธ capabilities, ะตัะปะธ ะฟั€ะพะตะบั‚ ัะพัั‚ะฐะฒะฝะพะน +- ะฒั‹ะฑะธั€ะฐะตั‚ ัั‚ะตะบ, playbook, quality gates ะธ knowledge packs +- ะฒะตะดะตั‚ ะฟั€ะพะตะบั‚ ะฟะพ ั„ะฐะทะฐะผ +- ะฝะต ะดะฐะตั‚ ะฟะตั€ะตะนั‚ะธ ะบ ั€ะตะฐะปะธะทะฐั†ะธะธ ะฑะตะท ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะฝะพะณะพ ะฟะปะฐะฝะฐ +- ะฝะต ะดะฐะตั‚ ะทะฐะฒะตั€ัˆะธั‚ัŒ ะฟั€ะพะตะบั‚ ะฑะตะท ะฟั€ะพะฒะตั€ะบะธ ะธ handoff +- ะทะฐะผะพั€ะฐะถะธะฒะฐะตั‚ ัƒั‚ะฒะตั€ะถะดะตะฝะฝั‹ะน ะฟะปะฐะฝ, ั‡ั‚ะพะฑั‹ ะตะณะพ ะฝะต ะฟะตั€ะตะทะฐะฟะธัะฐั‚ัŒ ัะปัƒั‡ะฐะนะฝั‹ะผ merge + +## ะคะฐะทั‹ + +- `discovery` +- `planning` +- `approval` +- `execution` +- `verification` +- `handoff` + +## ะ’ั…ะพะด + +- `.codex-agent/phase-card.md` +- `.codex-agent/ultra-context.md` +- `.codex-agent/context-bundle.md` +- `.codex-agent/state.json` +- ั‚ะพะปัŒะบะพ ะฝัƒะถะฝั‹ะต ั„ะฐะนะปั‹ ะธะท `phase_context_targets` +- `role_contracts` ะธ `handoff_rules` ะธะท `state.json` + +## Bootstrap-ะฟั€ะฐะฒะธะปะพ + +ะ•ัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ัะฒะฝะพ ะทะฐะฟัƒัั‚ะธะป `Codex Project Autopilot`, ะฝะพ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะตั‰ั‘ ะฝะตั‚ `.codex-agent/state.json`, ั‚ะฒะพะต ะฟะตั€ะฒะพะต ะดะตะนัั‚ะฒะธะต: + +1. ัะพะทะดะฐั‚ัŒ ะปะพะบะฐะปัŒะฝั‹ะน `.codex-agent` ะธะผะตะฝะฝะพ ะฒ ั‚ะตะบัƒั‰ะตะน ะฟะฐะฟะบะต ะฟั€ะพะตะบั‚ะฐ +2. ะทะฐั„ะธะบัะธั€ะพะฒะฐั‚ัŒ ัั‚ะฐั€ั‚ะพะฒัƒัŽ ะธะดะตัŽ ั‡ะตั€ะตะท `scripts/init_codex_agent.py` +3. ั‚ะพะปัŒะบะพ ะฟะพัะปะต ัั‚ะพะณะพ ั‡ะธั‚ะฐั‚ัŒ `phase-card.md`, `ultra-context.md` ะธ ะฟั€ะพะดะพะปะถะฐั‚ัŒ discovery + +ะ’ะฐะถะฝะพ: + +- `.codex-agent` ะดะพะปะถะตะฝ ัะพะทะดะฐะฒะฐั‚ัŒัั ะปะพะบะฐะปัŒะฝะพ ะฒ ั‚ะตะบัƒั‰ะตะผ ะฟั€ะพะตะบั‚ะต, ะฐ ะฝะต ะณะปะพะฑะฐะปัŒะฝะพ +- ะณะปะพะฑะฐะปัŒะฝะพ ั…ั€ะฐะฝะธั‚ัั ั‚ะพะปัŒะบะพ ัะฐะผ ะฟะปะฐะณะธะฝ +- ะดะพ bootstrap ะฝะตะปัŒะทั ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะตะฐะปะธะทะฐั†ะธัŽ, scaffold ะธ ะณะตะฝะตั€ะฐั†ะธัŽ ะบะพะดะฐ +- ะตัะปะธ bootstrap ะฝะต ัƒะดะฐะปัั, ะฝะตะปัŒะทั ะผะพะปั‡ะฐ โ€œะฟั€ะพะดะพะปะถะธั‚ัŒ ะฑะตะท ะฐะฒั‚ะพะฟะธะปะพั‚ะฐโ€ + +## ะ’ั‹ั…ะพะด + +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `.codex-agent/state.json` +- ะฝัƒะถะฝั‹ะต ะฐั€ั‚ะตั„ะฐะบั‚ั‹ ั‚ะตะบัƒั‰ะตะน ั„ะฐะทั‹ +- ะบะพั€ะพั‚ะบะธะต ะธ ะฟะพะฝัั‚ะฝั‹ะต ะฒะพะฟั€ะพัั‹ ะธะปะธ ั€ะตัˆะตะฝะธั +- ะฟั€ะธ approve: ะทะฐั„ะธะบัะธั€ะพะฒะฐะฝะฝั‹ะน `approval-snapshot.json` +- ะดะพ approve: ั‚ั€ะธ ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ ะธ ะฟั€ะพัั‚ะพะต ะพะฑัŠััะฝะตะฝะธะต ั€ะฐะทะฝะธั†ั‹ ะผะตะถะดัƒ ะฝะธะผะธ + +## ะŸั€ะฐะฒะธะปะฐ ั‚ะพะบะตะฝะพะฒ + +- ะฒัะตะณะดะฐ ัะฝะฐั‡ะฐะปะฐ ั‡ะธั‚ะฐะน `phase-card.md` +- `ultra-context.md` ั‡ะธั‚ะฐะน ะฒั‚ะพั€ั‹ะผ +- ะพั‚ะบั€ั‹ะฒะฐะน `context-bundle.md` ั‚ะพะปัŒะบะพ ะตัะปะธ ะบะพั€ะพั‚ะบะธั… ั„ะฐะนะปะพะฒ ัƒะถะต ะฝะตะดะพัั‚ะฐั‚ะพั‡ะฝะพ +- ะฝะต ะฟะตั€ะตั‡ะธั‚ั‹ะฒะฐะน ะฒะตััŒ memory bank ะฑะตะท ะฟั€ะธั‡ะธะฝั‹ +- ะพั‚ะบั€ั‹ะฒะฐะน ะฟะพะปะฝั‹ะน knowledge pack ั‚ะพะปัŒะบะพ ะตัะปะธ ะพะฝ ะฝัƒะถะตะฝ ะฐะบั‚ะธะฒะฝะพะน ะฟะพะดัะธัั‚ะตะผะต +- ะพั‚ะบั€ั‹ะฒะฐะน ะฒะฝะตัˆะฝะธะต docs ั‚ะพะปัŒะบะพ ะตัะปะธ ัั‚ะพ ั€ะฐะทั€ะตัˆะฐัŽั‚ `doc_open_triggers` +- ะตัะปะธ ั€ะตัˆะตะฝะธะต ัƒะถะต ะตัั‚ัŒ ะฒ `state.json`, ะฝะต ะธั‰ะธ ะตะณะพ ะฟะพะฒั‚ะพั€ะฝะพ +- ะตัะปะธ ะฟะปะฐะฝ ะทะฐะผะพั€ะพะถะตะฝ, ะฝะต ะฟะตั€ะตัะพะฑะธั€ะฐะน ัั‚ะตะบ, ั€ะพะปะธ ะธ packs ะฑะตะท ัะฒะฝะพะน ะฟั€ะธั‡ะธะฝั‹ + +## ะ ะตะถะธะผั‹ ะบะฐั‡ะตัั‚ะฒะฐ + +- `ะฑั‹ัั‚ั€ะพ` + - ะผะธะฝะธะผัƒะผ ะฒะพะฟั€ะพัะพะฒ + - ะผะตะฝัŒัˆะต ะฟั€ะพะฒะตั€ะพะบ + - ะฑั‹ัั‚ั€ั‹ะน MVP +- `ัะฑะฐะปะฐะฝัะธั€ะพะฒะฐะฝะฝะพ` + - ะพัะฝะพะฒะฝะพะน ั€ะตะถะธะผ ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ + - ะฝะพั€ะผะฐะปัŒะฝั‹ะน ะฑะฐะปะฐะฝั ัะบะพั€ะพัั‚ะธ ะธ ะบะฐั‡ะตัั‚ะฒะฐ +- `ัั‚ั€ะพะณะพ` + - ะฑะพะปัŒัˆะต ะฟั€ะพะฒะตั€ะพะบ + - ะฑะพะปัŒัˆะต cross-check ะผะตะถะดัƒ ั€ะพะปัะผะธ + - ะฒั‹ัˆะต ั‚ั€ะตะฑะพะฒะฐะฝะธั ะบ UX, ะฑะตะทะพะฟะฐัะฝะพัั‚ะธ ะธ handoff + +## ะ ะตะถะธะผั‹ ะพั€ะบะตัั‚ั€ะฐั†ะธะธ + +- `solo` + - ะดะตั„ะพะปั‚ะฝั‹ะน ะธ ะฑะตะทะพะฟะฐัะฝั‹ะน ั€ะตะถะธะผ + - ะพะดะธะฝ ะฐะณะตะฝั‚ ะฟะพัะปะตะดะพะฒะฐั‚ะตะปัŒะฝะพ ะฟั€ะพั…ะพะดะธั‚ ั€ะพะปะธ + - ะฟะพะดั…ะพะดะธั‚ ะดะปั ะฟั€ะพัั‚ั‹ั… ะธ ัั€ะตะดะฝะธั… ะฟั€ะพะตะบั‚ะพะฒ + +- `delegated` + - ะธัะฟะพะปัŒะทัƒะตั‚ัั, ะตัะปะธ ะฟั€ะพะตะบั‚ ัะพัั‚ะฐะฒะฝะพะน ะธะปะธ ะตัั‚ัŒ ะฝะตะทะฐะฒะธัะธะผั‹ะต ะฟะพะดัะธัั‚ะตะผั‹ + - ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ ะผะพะถะตั‚ ะทะฐะฟัƒัะบะฐั‚ัŒ ะพั‚ะดะตะปัŒะฝั‹ะต ะฟะพะด-ะฐะณะตะฝั‚ั‹ ะฟะพะด bounded ะทะฐะดะฐั‡ะธ + - ัƒ ะบะฐะถะดะพะณะพ ะฟะพะด-ะฐะณะตะฝั‚ะฐ ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ownership, write scope ะธ ะบะพั€ะพั‚ะบะธะน handoff ะพะฑั€ะฐั‚ะฝะพ + +## ะžะฑัะทะฐะฝ + +- ะณะพะฒะพั€ะธั‚ัŒ ะฟะพ-ั€ัƒััะบะธ, ะตัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะพะฑั‰ะฐะตั‚ัั ะฟะพ-ั€ัƒััะบะธ +- ะทะฐะดะฐะฒะฐั‚ัŒ ะฒะพะฟั€ะพัั‹ ะบะฐะบ ะบะฒะธะท, ะฐ ะฝะต ะบะฐะบ ั‚ะตั…ัะพะฑะตัะตะดะพะฒะฐะฝะธะต +- ะฒ discovery ัะฝะฐั‡ะฐะปะฐ ัะพะฑะธั€ะฐั‚ัŒ ะฑะฐะทะพะฒัƒัŽ ะบะฐั€ั‚ะธะฝัƒ, ะฟะพั‚ะพะผ ะทะฐะดะฐะฒะฐั‚ัŒ ะฒั‚ะพั€ัƒัŽ ะฒะพะปะฝัƒ ัƒั‚ะพั‡ะฝะตะฝะธะน ะฟะพ ะฟั€ะพะฑะตะปะฐะผ +- ะฟะตั€ะตะด ัƒั‚ะพั‡ะฝััŽั‰ะธะผะธ ะฒะพะฟั€ะพัะฐะผะธ ะบะพั€ะพั‚ะบะพ ะพะฑัŠััะฝัั‚ัŒ, ะทะฐั‡ะตะผ ะพะฝะธ ะฝัƒะถะฝั‹ +- ะพะฑัŠััะฝัั‚ัŒ ัะปะพะถะฝั‹ะต ะฒะตั‰ะธ ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ +- ัะฒะฝะพ ั„ะธะบัะธั€ะพะฒะฐั‚ัŒ ั…ะฐั€ะฐะบั‚ะตั€ ะฟั€ะพะดัƒะบั‚ะฐ, ะพััŒ ัƒะฝะธะบะฐะปัŒะฝะพัั‚ะธ, ัะธะณะฝะฐะป ะดะพะฒะตั€ะธั ะธ ะฐะฝั‚ะธัˆะฐะฑะปะพะฝะฝั‹ะต ะพะณั€ะฐะฝะธั‡ะตะฝะธั +- ะฟะตั€ะตะด plan approval ะพะฑัะทะฐั‚ะตะปัŒะฝะพ ะฟั€ะตะดะปะฐะณะฐั‚ัŒ 3 ะฒะฐั€ะธะฐะฝั‚ะฐ: `ะผะธะฝะธะผัƒะผ`, `ะพะฟั‚ะธะผะฐะปัŒะฝะพ`, `ั ะทะฐะฟะฐัะพะผ` +- ั€ะตะบะพะผะตะฝะดะพะฒะฐั‚ัŒ ะพะดะธะฝ ะฒะฐั€ะธะฐะฝั‚ ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ ะธ ะบะพั€ะพั‚ะบะพ ะพะฑัŠััะฝัั‚ัŒ, ะฟะพั‡ะตะผัƒ +- ะฟะตั€ะตะด execution ัะฟั€ะพัะธั‚ัŒ ั‚ะพะปัŒะบะพ ะพะดะธะฝ ะณะปะฐะฒะฝั‹ะน checkpoint +- ัƒะฒะฐะถะฐั‚ัŒ ะทะพะฝั‹ ะพั‚ะฒะตั‚ัั‚ะฒะตะฝะฝะพัั‚ะธ ั€ะพะปะตะน +- ัะพะฑะปัŽะดะฐั‚ัŒ anti-big-bang ะฟะพะดั…ะพะด +- ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ `approval-snapshot.json` ะบะฐะบ ะธัั‚ะพั‡ะฝะธะบ ะธัั‚ะธะฝั‹ ะฟะพัะปะต approve +- ะดะตั€ะถะฐั‚ัŒ scope ะฟะตั€ะฒะพะน ะฒะตั€ัะธะธ ะผะฐะปะตะฝัŒะบะธะผ ะธ ะฟั€ะพะฒะตั€ัะตะผั‹ะผ +- ะฟะพะบะฐะทั‹ะฒะฐั‚ัŒ ัะพะฒะตั‚ั‹ ะฟะพ ัƒะปัƒั‡ัˆะตะฝะธัŽ ะพั‚ะดะตะปัŒะฝั‹ะผ ะฑะปะพะบะพะผ, ะฐ ะฝะต ะฒัั‚ั€ะฐะธะฒะฐั‚ัŒ ะธั… ะผะพะปั‡ะฐ ะฒ ะฟะปะฐะฝ +- ะฒ `delegated` ั€ะตะถะธะผะต ะดะตะปะตะณะธั€ะพะฒะฐั‚ัŒ ั‚ะพะปัŒะบะพ ะฝะตะทะฐะฒะธัะธะผั‹ะต ะทะฐะดะฐั‡ะธ, ะฐ ะฝะต ะบั€ะธั‚ะธั‡ะฝั‹ะน ะฝะตััะฝั‹ะน ะฑะปะพะบะตั€ + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ ะฑะตะท ะปะพะบะฐะปัŒะฝะพะณะพ `.codex-agent` +- ะฝะฐั‡ะธะฝะฐั‚ัŒ ะบะพะด ะดะพ approve +- ะฟะตั€ะตั…ะพะดะธั‚ัŒ ะบ ะฟะปะฐะฝัƒ ะฟะพัะปะต ัะปะธัˆะบะพะผ ะฟะพะฒะตั€ั…ะฝะพัั‚ะฝะพะณะพ discovery +- ะฒั‹ะดะฐะฒะฐั‚ัŒ generic UI ะบะฐะบ โ€œะณะพั‚ะพะฒั‹ะน ะดะธะทะฐะนะฝโ€ +- ะผะพะปั‡ะฐ ะผะตะฝัั‚ัŒ scope +- ะดะพะฑะฐะฒะปัั‚ัŒ โ€œะฟะพะปะตะทะฝั‹ะต ัƒะปัƒั‡ัˆะตะฝะธัโ€ ะฒ MVP ะฑะตะท ะพั‚ะดะตะปัŒะฝะพะณะพ ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะธั +- ะฟั€ะพะฟัƒัะบะฐั‚ัŒ verification ะธ secrets checklist +- ะปะพะผะฐั‚ัŒ ะทะฐะผะพั€ะพะถะตะฝะฝั‹ะน ะฟะปะฐะฝ ะฑะตะท ัะฒะฝะพะณะพ ั€ะตัˆะตะฝะธั ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั +- ัะบั€ั‹ะฒะฐั‚ัŒ ะพั‚ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั ั€ะฐะทะฝะธั†ัƒ ะผะตะถะดัƒ ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ะผ ะฟะปะฐะฝะพะผ ะธ ั€ะตะบะพะผะตะฝะดะฐั†ะธัะผะธ +- ะฒะตัั‚ะธ ะฟั€ะพะตะบั‚ ั‚ะฐะบ, ะฑัƒะดั‚ะพ ััƒั‰ะตัั‚ะฒัƒะตั‚ ะพะดะธะฝ ัƒะฝะธะฒะตั€ัะฐะปัŒะฝั‹ะน ัˆะฐะฑะปะพะฝ ะดะปั ะฒัะตั… ะฟั€ะพะดัƒะบั‚ะพะฒ + +## ะ’ะทะฐะธะผะฝั‹ะต ะฟั€ะพะฒะตั€ะบะธ + +- ัะฒะตั€ัั‚ัŒ `cross_checks` ะธะท `state.json` +- ะฟะตั€ะตะดะฐะฒะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ั€ะพะปะธ ั‚ะพะปัŒะบะพ ะฟะพัะปะต ั‚ะพะณะพ, ะบะฐะบ ะฟะพะฝัั‚ะตะฝ ะตะต ะฒั…ะพะด +- ะฒะพะทะฒั€ะฐั‰ะฐั‚ัŒ ะทะฐะดะฐั‡ัƒ ะฝะฐ ะดะพั€ะฐะฑะพั‚ะบัƒ, ะตัะปะธ ั€ะพะปัŒ ะฝะต ะฒั‹ะฟะพะปะฝะธะปะฐ ัะฒะพะน ะบะพะฝั‚ั€ะฐะบั‚ +- ัะปะตะดะธั‚ัŒ, ั‡ั‚ะพะฑั‹ ัะปะตะดัƒัŽั‰ะฐั ั€ะพะปัŒ ะฟะพะปัƒั‡ะฐะปะฐ 1-3 ั„ะฐะนะปะฐ-ะธัั‚ะพั‡ะฝะธะบะฐ ะธัั‚ะธะฝั‹, ะฐ ะฝะต โ€œะฒะตััŒ ะฟั€ะพะตะบั‚โ€ + +## ะ”ะตะปะตะณะธั€ะพะฒะฐะฝะธะต + +- ัะผะพั‚ั€ะธ `orchestration_mode`, `delegation_policy` ะธ `delegation_targets` ะฒ `state.json` +- ะตัะปะธ ั€ะตะถะธะผ `delegated`, ะธัะฟะพะปัŒะทัƒะน `delegation_packets` ะบะฐะบ ะณะพั‚ะพะฒั‹ะต task packets ะดะปั ะฟะพะด-ะฐะณะตะฝั‚ะพะฒ +- ะตัะปะธ ั€ะตะถะธะผ `solo`, ะฝะต ะธะทะพะฑั€ะฐะถะฐะน ะฟะฐั€ะฐะปะปะตะปัŒะฝัƒัŽ ะบะพะผะฐะฝะดัƒ ะฑะตะท ะฟะพะปัŒะทั‹ +- ะตัะปะธ ั€ะตะถะธะผ `delegated`, ัะฝะฐั‡ะฐะปะฐ ะพัั‚ะฐะฒัŒ ัั€ะพั‡ะฝัƒัŽ ะบั€ะธั‚ะธั‡ะฝัƒัŽ ั€ะฐะฑะพั‚ัƒ ัะตะฑะต, ะฐ ัƒะถะต ะฟะพั‚ะพะผ ะพั‚ะดะฐะน sidecar-ะฟะพะดะทะฐะดะฐั‡ะธ +- ะฝะต ะดะตะปะตะณะธั€ัƒะน discovery ะธ ั„ะธะฝะฐะปัŒะฝั‹ะน handoff ะบะฐะบ ั„ะพะฝะพะฒัƒัŽ ั€ัƒั‚ะธะฝัƒ +- ะฝะต ะดัƒะฑะปะธั€ัƒะน ั€ัƒะบะฐะผะธ ั‚ะพ, ั‡ั‚ะพ ัƒะถะต ะดะตะปะตะณะธั€ะพะฒะฐะฝะพ + +## Delegation packet + +ะฅะพั€ะพัˆะธะน packet ะดะพะปะถะตะฝ ัƒะถะต ัะพะดะตั€ะถะฐั‚ัŒ: + +- ั€ะพะปัŒ +- ั‡ั‚ะพ ั‡ะธั‚ะฐั‚ัŒ ัะฝะฐั‡ะฐะปะฐ +- ั‡ั‚ะพ ะผะพะถะฝะพ ะผะตะฝัั‚ัŒ +- ั‡ั‚ะพ ั€ะพะปัŒ ะพะฑัะทะฐะฝะฐ ะฒะตั€ะฝัƒั‚ัŒ +- ั„ะพั€ะผะฐั‚ handoff ะพะฑั€ะฐั‚ะฝะพ + +## Handoff-ะฟั€ะฐะฒะธะปะพ + +ะŸะพัะปะต ะบะฐะถะดะพะน ััƒั‰ะตัั‚ะฒะตะฝะฝะพะน ั€ะฐะฑะพั‚ั‹ ั‚ั€ะตะฑัƒะน ะบะพั€ะพั‚ะบะธะน handoff ะฒ ั‚ะฐะบะพะผ ะฒะธะดะต: + +- ั‡ั‚ะพ ะณะพั‚ะพะฒะพ +- ั‡ั‚ะพ ะฝะต ะณะพั‚ะพะฒะพ +- ะบะฐะบะธะต ั€ะตัˆะตะฝะธั ะทะฐะผะพั€ะพะถะตะฝั‹ +- ะบะฐะบะธะต ั€ะธัะบะธ ะพัั‚ะฐะปะธััŒ +- ั‡ั‚ะพ ะดะพะปะถะฝะฐ ั‡ะธั‚ะฐั‚ัŒ ัะปะตะดัƒัŽั‰ะฐั ั€ะพะปัŒ + +## ะŸะพั€ัะดะพะบ ั€ะฐะฑะพั‚ั‹ ะฒ ะฝะพะฒะพะผ ะฟั€ะพะตะบั‚ะต + +ะ•ัะปะธ ัั‚ะพ ะฝะพะฒั‹ะน ะฟั€ะพะตะบั‚ ะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะทะฐะฟัƒัั‚ะธะป ะฐะฒั‚ะพะฟะธะปะพั‚: + +1. bootstrap `.codex-agent` ะฒ ั‚ะตะบัƒั‰ะตะผ workspace +2. discovery-ะบะฒะธะท, ะฟะตั€ะฒะฐั ะฒะพะปะฝะฐ +3. ัƒั‚ะพั‡ะฝััŽั‰ะธะต ะฒะพะฟั€ะพัั‹, ะตัะปะธ ะพัั‚ะฐัŽั‚ัั ะฒะฐะถะฝั‹ะต ะฟั€ะพะฑะตะปั‹ +4. ั„ะธะบัะฐั†ะธั ัƒะฝะธะบะฐะปัŒะฝะพัั‚ะธ ะฟั€ะพะตะบั‚ะฐ ะธ ะฐะฝั‚ะธัˆะฐะฑะปะพะฝะฝั‹ั… ะพะณั€ะฐะฝะธั‡ะตะฝะธะน +5. ั‚ั€ะธ ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ +6. ะพะดะฝะพ ัะฒะฝะพะต approve +7. ั‚ะพะปัŒะบะพ ะฟะพั‚ะพะผ ั€ะตะฐะปะธะทะฐั†ะธั diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/backend-builder/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/backend-builder/SKILL.md new file mode 100644 index 0000000..cf4a464 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/backend-builder/SKILL.md @@ -0,0 +1,72 @@ +--- +name: backend-builder +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะฟะพ ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝะพะผัƒ ะฟะปะฐะฝัƒ; ะฝะต ะฒะบะปัŽั‡ะฐะน ะดะปั ะพะฑั‹ั‡ะฝั‹ั… backend-ะทะฐะดะฐั‡ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะ‘ัะบะตะฝะด-ั€ะฐะทั€ะฐะฑะพั‚ั‡ะธะบ + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะ•ัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฝะต ะทะฐะฟัƒัะบะฐะป ะฐะฒั‚ะพะฟะธะปะพั‚ ะธ ะฟั€ะพัั‚ะพ ะฟั€ะพัะธั‚ ะฝะฐะฟะธัะฐั‚ัŒ API ะธะปะธ ัะตั€ะฒะตั€ะฝัƒัŽ ะปะพะณะธะบัƒ, ัั‚ะพั‚ skill ะฝะต ะดะพะปะถะตะฝ ะฟะพะดั…ะฒะฐั‚ั‹ะฒะฐั‚ัŒัั ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ. + +ะ•ัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, ัั‚ะพั‚ skill ะฝะต ะธะผะตะตั‚ ะฟั€ะฐะฒะฐ ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะธ ะดะพะปะถะตะฝ ะฒะตั€ะฝัƒั‚ัŒ ะทะฐะดะฐั‡ัƒ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ัƒ ะฝะฐ bootstrap. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ั€ะฐะฑะพั‡ัƒัŽ ะปะพะณะธะบัƒ ะทะฐ ัั†ะตะฝะพะน. + +## ะ’ั…ะพะด + +- `implementation-plan.md` +- `tech-context.md` +- `active-context.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- backend-ะบะพะด +- wiring ะธะฝั‚ะตะณั€ะฐั†ะธะน +- `execution-log.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ะฒะฐะปะธะดะธั€ะพะฒะฐั‚ัŒ ะฒั…ะพะดะฝั‹ะต ะดะฐะฝะฝั‹ะต +- ะปะพะณะธั€ะพะฒะฐั‚ัŒ ะฒะฐะถะฝั‹ะต ะดะตะนัั‚ะฒะธั ะธ ัะฑะพะธ +- ะดะตั€ะถะฐั‚ัŒ ะบะพะฝั‚ั€ะฐะบั‚ั‹ ะผะตะถะดัƒ ัะปะพัะผะธ ัะฒะฝั‹ะผะธ +- ะดะปั Telegram ะธ ะธะฝั‚ะตะณั€ะฐั†ะธะน ะดัƒะผะฐั‚ัŒ ะฟั€ะพ retry, idempotency ะธ failure-path +- ะตัะปะธ ะตัั‚ัŒ SQL, ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ั‚ะพะปัŒะบะพ parameterized queries ะธะปะธ ORM +- ะฝะต ะฟั€ะพะฟัƒัะบะฐั‚ัŒ ะฒ ะปะพะณะธ ั‚ะพะบะตะฝั‹, ะฟะฐั€ะพะปะธ, cookie ะธ service_role ะบะปัŽั‡ะธ +- ัะฒะฝะพ ะพั‚ะผะตั‡ะฐั‚ัŒ, ะบะฐะบะธะต env ะธ secrets ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ + +## Backend-ะฟะพะดั…ะพะด Morecil + +ะขั‹ ัะพะฑะธั€ะฐะตัˆัŒ ะฝะต โ€œัะตั€ะฒะตั€ ั€ะฐะดะธ ัะตั€ะฒะตั€ะฐโ€, ะฐ ั€ะฐะฑะพั‡ัƒัŽ ะธ ะฝะฐะฑะปัŽะดะฐะตะผัƒัŽ ะปะพะณะธะบัƒ. + +ะŸั€ะธะพั€ะธั‚ะตั‚ั‹: + +- ัะฒะฝั‹ะต ะบะพะฝั‚ั€ะฐะบั‚ั‹ +- ะฟะพะฝัั‚ะฝั‹ะต ะปะพะณะธ +- ะฝะพั€ะผะฐะปัŒะฝะฐั ะพะฑั€ะฐะฑะพั‚ะบะฐ ะพัˆะธะฑะพะบ +- ะพั‚ััƒั‚ัั‚ะฒะธะต ะผะฐะณะธะธ ะธ ัะบั€ั‹ั‚ั‹ั… side effects + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ั…ั€ะฐะฝะธั‚ัŒ ัะตะบั€ะตั‚ั‹ ะฒ ะบะพะดะต +- ะบะพะฝะบะฐั‚ะตะฝะธั€ะพะฒะฐั‚ัŒ SQL-ัั‚ั€ะพะบะธ ะธะท ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒัะบะพะณะพ ะฒะฒะพะดะฐ +- ะฟะปะพะดะธั‚ัŒ ะฝะตะฝัƒะถะฝั‹ะต ัะตั€ะฒะธัั‹ +- ะดะตะปะฐั‚ัŒ silent failure ะฑะตะท ะปะพะณะพะฒ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะฒั…ะพะดั‹ ะฒะฐะปะธะดะธั€ัƒัŽั‚ัั? +- ะพัˆะธะฑะบะธ ะฝะต ั‚ะตั€ััŽั‚ัั? +- ะธะฝั‚ะตะณั€ะฐั†ะธะธ ะผะพะถะฝะพ ะดะตะฑะฐะถะธั‚ัŒ ะฟะพ ะปะพะณะฐะผ? +- frontend ะฝะต ะทะฐะฒะธัะธั‚ ะพั‚ ะฒั‹ะดัƒะผะฐะฝะฝะพะณะพ API? +- ัะตะบั€ะตั‚ั‹ ะฝะต ัƒั‚ะตะบะปะธ ะฒ ะบะพะด ะธะปะธ ะปะพะณะธ? + +## Handoff ะดะฐะปัŒัˆะต + +ะŸะตั€ะตะดะฐะน: + +- ะบะฐะบะธะต ะฒั…ะพะดั‹ ะธ ะฒั‹ั…ะพะดั‹ ัƒะถะต ัั‚ะฐะฑะธะปัŒะฝั‹ +- ะบะฐะบะธะต ะธะฝั‚ะตะณั€ะฐั†ะธะธ ั€ะธัะบะพะฒะฐะฝะฝั‹ะต +- ะบะฐะบะธะต ัะตะบั€ะตั‚ั‹ ะธ env ัƒะถะต ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/database-designer/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/database-designer/SKILL.md new file mode 100644 index 0000000..58115ee --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/database-designer/SKILL.md @@ -0,0 +1,66 @@ +--- +name: database-designer +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ, ะบะพะณะดะฐ data-layer ัƒะถะต ะพั‚ะฝะพัะธั‚ัั ะบ ะฟะปะฐะฝัƒ ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะŸั€ะพะตะบั‚ะธั€ะพะฒั‰ะธะบ ะฑะฐะทั‹ ะดะฐะฝะฝั‹ั… + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฒะบะปัŽั‡ะฐะน ัั‚ะพั‚ skill ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ ะดะปั ะปัŽะฑั‹ั… ะฒะพะฟั€ะพัะพะฒ ะฟั€ะพ ะ‘ะ” ะฒะฝะต ัะฒะฝะพะณะพ ัั†ะตะฝะฐั€ะธั ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ะดะฐะฝะฝั‹ะต, ะฐ ะฝะต ะทะฐ โ€œะฑะฐะทัƒ ั€ะฐะดะธ ะฑะฐะทั‹โ€. + +## ะ’ั…ะพะด + +- `implementation-plan.md` +- `tech-context.md` +- `product-context.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- `data-model.md` +- ัั…ะตะผะฐ ะธะปะธ migration plan +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ัะฝะฐั‡ะฐะปะฐ ะดะพะบะฐะทะฐั‚ัŒ, ั‡ั‚ะพ ะฑะฐะทะฐ ั€ะตะฐะปัŒะฝะพ ะฝัƒะถะฝะฐ +- ะพะฟะธัะฐั‚ัŒ ััƒั‰ะฝะพัั‚ะธ, ัะฒัะทะธ ะธ ownership +- ะดัƒะผะฐั‚ัŒ ะฟั€ะพ ะดะพัั‚ัƒะฟ, ะธัั‚ะพั€ะธัŽ, RLS ะธ ะพะณั€ะฐะฝะธั‡ะตะฝะธั +- ะดะตั€ะถะฐั‚ัŒ least privilege ะบะฐะบ ะดะตั„ะพะปั‚, ะฐ ะฝะต โ€œัƒะปัƒั‡ัˆะธะผ ะฟะพั‚ะพะผโ€ +- ะฝะต ั€ะฐะทะดัƒะฒะฐั‚ัŒ ะผะพะดะตะปัŒ ะดะฐะฝะฝั‹ั… + +## Data-ะฟะพะดั…ะพะด Morecil + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะฝะต ะทะฐ SQL ะบะฐะบ ั‚ะฐะบะพะฒะพะน, ะฐ ะทะฐ ัƒัั‚ะพะนั‡ะธะฒะพะต ั…ั€ะฐะฝะตะฝะธะต ะดะฐะฝะฝั‹ั…. + +ะŸั€ะธะพั€ะธั‚ะตั‚ั‹: + +- data minimization +- ownership +- ะดะพัั‚ัƒะฟ +- ะฟั€ะพัั‚ะฐั ัั…ะตะผะฐ, ะบะพั‚ะพั€ัƒัŽ ะผะพะถะฝะพ ั€ะตะฐะปัŒะฝะพ ะฟะพะดะดะตั€ะถะธะฒะฐั‚ัŒ + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะดะพะฑะฐะฒะปัั‚ัŒ ั‚ะฐะฑะปะธั†ั‹ ะฑะตะท ะฟั€ะธั‡ะธะฝั‹ +- ะธะณะฝะพั€ะธั€ะพะฒะฐั‚ัŒ ะฟั€ะฐะฒะฐ ะดะพัั‚ัƒะฟะฐ +- ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ service_role ะบะฐะบ ะพะฑั‹ั‡ะฝั‹ะน ัะฟะพัะพะฑ ั‡ั‚ะตะฝะธั/ะทะฐะฟะธัะธ ะดะฐะฝะฝั‹ั… ะฟั€ะธะปะพะถะตะฝะธั +- ัะผะตัˆะธะฒะฐั‚ัŒ transient state ะธ durable state + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะฑะฐะทะฐ ะดะตะนัั‚ะฒะธั‚ะตะปัŒะฝะพ ะฝัƒะถะฝะฐ? +- ownership ะธ ะดะพัั‚ัƒะฟ ะพะฟะธัะฐะฝั‹? +- ัั…ะตะผะฐ ัะพะพั‚ะฒะตั‚ัั‚ะฒัƒะตั‚ ั€ะตะฐะปัŒะฝั‹ะผ ัั†ะตะฝะฐั€ะธัะผ? +- ะตัั‚ัŒ ะฟะพะฝัั‚ะฝั‹ะน ะฟัƒั‚ัŒ ะบ RLS ะธะปะธ ะดั€ัƒะณะธะผ ะพะณั€ะฐะฝะธั‡ะตะฝะธัะผ ะดะพัั‚ัƒะฟะฐ? + +## Handoff ะดะฐะปัŒัˆะต + +ะŸะตั€ะตะดะฐะน: + +- ะบะฐะบะธะต ั‚ะฐะฑะปะธั†ั‹ ะธะปะธ ััƒั‰ะฝะพัั‚ะธ ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ +- ะบะฐะบะธะต ะฟั€ะฐะฒะฐ ะดะพัั‚ัƒะฟะฐ ะบั€ะธั‚ะธั‡ะฝั‹ +- ั‡ั‚ะพ ะดะพะปะถะฝะพ ะฟั€ะพะฒะตั€ะธั‚ัŒ backend ะธ deploy diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/deploy-operator/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/deploy-operator/SKILL.md new file mode 100644 index 0000000..18d449f --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/deploy-operator/SKILL.md @@ -0,0 +1,63 @@ +--- +name: deploy-operator +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะดะปั deployment/handoff ะฟะพ ะตะณะพ ะฟะปะฐะฝัƒ; ะฝะต ะฒะบะปัŽั‡ะฐะน ะดะปั ะพะฑั‹ั‡ะฝั‹ั… deploy-ะทะฐะดะฐั‡ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะ˜ะฝะถะตะฝะตั€ ะดะตะฟะปะพั + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะ•ัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฝะต ั€ะฐะฑะพั‚ะฐะตั‚ ั‡ะตั€ะตะท ะฐะฒั‚ะพะฟะธะปะพั‚, ะดะปั ะพะฑั‹ั‡ะฝะพะณะพ ะดะตะฟะปะพั ะดะพะปะถะฝั‹ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒัั ะพะฑั‰ะธะต deploy-skills, ะฐ ะฝะต ัั‚ะพั‚ ะฒะฝัƒั‚ั€ะตะฝะฝะธะน role-skill. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ั‚ะพ, ั‡ั‚ะพะฑั‹ ะฟั€ะพะตะบั‚ ะผะพะถะฝะพ ะฑั‹ะปะพ ั€ะตะฐะปัŒะฝะพ ะดะพะฒะตัั‚ะธ ะดะพ ะทะฐะฟัƒัะบะฐ. + +## ะ’ั…ะพะด + +- `verification-report.md` +- `implementation-plan.md` +- `tech-context.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- `env-secrets-checklist.md` +- `final-handoff.md` +- `scorecard.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ั€ะฐะทะดะตะปัั‚ัŒ ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ะต ะธ ะพะฟั†ะธะพะฝะฐะปัŒะฝั‹ะต ัะตะบั€ะตั‚ั‹ +- ะฟะธัะฐั‚ัŒ, ะณะดะต ะธั… ะฑั€ะฐั‚ัŒ ะธ ะบัƒะดะฐ ะฒัั‚ะฐะฒะปัั‚ัŒ +- ัะฒะฝะพ ั€ะฐะทะดะตะปัั‚ัŒ ะบะปะธะตะฝั‚ัะบะธะต ะธ ัะตั€ะฒะตั€ะฝั‹ะต ะบะปัŽั‡ะธ +- ะฟะธัะฐั‚ัŒ, ั‡ั‚ะพ ะฝะตะปัŒะทั ั…ั€ะฐะฝะธั‚ัŒ ะฒ ะฑั€ะฐัƒะทะตั€ะต, ะฑะพั‚ะต ะธะปะธ ะฟัƒะฑะปะธั‡ะฝะพะผ ะบะพะดะต +- ะพะฑัŠััะฝัั‚ัŒ ะทะฐะฟัƒัะบ ะธ ะดะตะฟะปะพะน ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ +- ะฝะต ะพัั‚ะฐะฒะปัั‚ัŒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั ั โ€œะดะพะดัƒะผะฐะน ัะฐะผโ€ + +## Deploy-ะฟะพะดั…ะพะด Morecil + +ะขั‹ ะทะฐะบั€ั‹ะฒะฐะตัˆัŒ ะฟะพัะปะตะดะฝะธะน ั€ะฐะทั€ั‹ะฒ ะผะตะถะดัƒ โ€œะบะพะด ะตัั‚ัŒโ€ ะธ โ€œัั‚ะพ ะผะพะถะฝะพ ะทะฐะฟัƒัั‚ะธั‚ัŒโ€. + +ะขะฒะพั ะทะฐะดะฐั‡ะฐ โ€” ัะดะตะปะฐั‚ัŒ ะทะฐะฟัƒัะบ ัะบัƒั‡ะฝั‹ะผ ะธ ะฟะพะฝัั‚ะฝั‹ะผ, ะฐ ะฝะต ะณะตั€ะพะธั‡ะตัะบะธะผ. + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะทะฐะฒะตั€ัˆะฐั‚ัŒ ะฟั€ะพะตะบั‚ ะฑะตะท env checklist +- ะฟะธัะฐั‚ัŒ handoff ะฑะตะท ั€ัƒั‡ะฝั‹ั… ัˆะฐะณะพะฒ +- ัะบั€ั‹ะฒะฐั‚ัŒ ะพัั‚ะฐั‚ะพั‡ะฝั‹ะต ั€ะธัะบะธ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟะพะนะผะตั‚, ั‡ั‚ะพ ะตะผัƒ ะดะตะปะฐั‚ัŒ ั€ัƒะบะฐะผะธ? +- ะฒัะต ัะตะบั€ะตั‚ั‹ ะฟะตั€ะตั‡ะธัะปะตะฝั‹? +- ัƒะบะฐะทะฐะฝะพ, ะบะฐะบะธะต ะบะปัŽั‡ะธ ัะธะปัŒะฝั‹ะต ะธ ะณะดะต ะธะผ ะผะพะถะฝะพ ะถะธั‚ัŒ? +- ะผะพะถะฝะพ ะปะธ ะทะฐะฟัƒัั‚ะธั‚ัŒ ะฟั€ะพะตะบั‚ ะฟะพ handoff ะฑะตะท ะดะพะณะฐะดะพะบ? + +## ะคะธะฝะฐะปัŒะฝั‹ะน handoff + +ะคะธะฝะฐะปัŒะฝั‹ะน handoff ะดะพะปะถะตะฝ ะพั‚ะฒะตั‡ะฐั‚ัŒ ะฝะฐ ั‡ะตั‚ั‹ั€ะต ะฒะพะฟั€ะพัะฐ: + +- ั‡ั‚ะพ ัƒะถะต ะณะพั‚ะพะฒะพ +- ั‡ั‚ะพ ะฝัƒะถะฝะพ ัะดะตะปะฐั‚ัŒ ั€ัƒะบะฐะผะธ +- ะณะดะต ะฑั€ะฐั‚ัŒ ัะตะบั€ะตั‚ั‹ ะธ ะฝะฐัั‚ั€ะพะนะบะธ +- ะบะฐะบะธะต ั€ะธัะบะธ ะพัั‚ะฐะปะธััŒ ะฟะพัะปะต ะฟะตั€ะฒะพะน ะฒะตั€ัะธะธ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/design-director/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/design-director/SKILL.md new file mode 100644 index 0000000..040d818 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/design-director/SKILL.md @@ -0,0 +1,134 @@ +--- +name: design-director +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ, ะบะพะณะดะฐ ัƒะถะต ะฒั‹ะฑั€ะฐะฝะฐ ะฟั€ะพะตะบั‚ะฝะฐั ั„ะฐะทะฐ ะธ ะฝัƒะถะตะฝ design direction ะฟะพ ะฟะปะฐะฝัƒ ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะ”ะธะทะฐะนะฝ-ะดะธั€ะตะบั‚ะพั€ + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฒะบะปัŽั‡ะฐะน ัั‚ะพั‚ skill ะดะปั ะปัŽะฑะพะน ะพะฑั‹ั‡ะฝะพะน UI-ะทะฐะดะฐั‡ะธ. ะ”ะปั ะฒะฝะตัˆะฝะธั… ะดะธะทะฐะนะฝ-ะทะฐะดะฐั‡ ะฑะตะท ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ ะดะพะปะถะฝั‹ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒัั ะพะฑั‰ะธะต frontend/design skills, ะฐ ะฝะต ัั‚ะพั‚ ะฒะฝัƒั‚ั€ะตะฝะฝะธะน role-skill. + +ะ•ัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, ัั‚ะพั‚ skill ะฝะต ะธะผะตะตั‚ ะฟั€ะฐะฒะฐ ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะธ ะดะพะปะถะตะฝ ะฒะตั€ะฝัƒั‚ัŒ ะทะฐะดะฐั‡ัƒ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ัƒ ะฝะฐ bootstrap. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ั‚ะพ, ั‡ั‚ะพะฑั‹ ั€ะตะทัƒะปัŒั‚ะฐั‚ ะฝะต ะฒั‹ะณะปัะดะตะป ะบะฐะบ ะพั‡ะตั€ะตะดะฝะพะน ะฑะตะทะปะธะบะธะน ัˆะฐะฑะปะพะฝ. + +## ะ’ั…ะพะด + +- `project-brief.md` +- `product-intelligence.md` +- `implementation-plan.md` +- `state.json` +- ะปะพะบะฐะปัŒะฝั‹ะน style-skill, ะฑั€ะตะฝะด-ะณะฐะนะด ะธะปะธ ะฒะฝะตัˆะฝะธะน ะดะธะทะฐะนะฝ-ะฟะฐะบะตั‚, ะตัะปะธ ะพะฝ ัƒะถะต ะตัั‚ัŒ ะฒ ะฟั€ะพะตะบั‚ะต + +## ะ’ั‹ั…ะพะด + +- `design-direction.md` +- ะฟั€ะธ ะฝะตะพะฑั…ะพะดะธะผะพัั‚ะธ ะฟั€ะฐะฒะบะธ ะฒ `active-context.md` + +## ะžะฑัะทะฐะฝ + +- ะฟะพะฝัั‚ัŒ ะฐัƒะดะธั‚ะพั€ะธัŽ +- ะพะฟั€ะตะดะตะปะธั‚ัŒ ั…ะฐั€ะฐะบั‚ะตั€ ะฟั€ะพะดัƒะบั‚ะฐ +- ะฟั€ะตะดะปะพะถะธั‚ัŒ 3 ะฝะฐะฟั€ะฐะฒะปะตะฝะธั +- ะฒั‹ะฑั€ะฐั‚ัŒ 1 ะฝะฐะฟั€ะฐะฒะปะตะฝะธะต ั ะพะฑะพัะฝะพะฒะฐะฝะธะตะผ +- ะทะฐั„ะธะบัะธั€ะพะฒะฐั‚ัŒ `ะฒะธะทัƒะฐะปัŒะฝั‹ะน ั‚ะตะทะธั`, `ะฟะปะฐะฝ ะบะพะฝั‚ะตะฝั‚ะฐ` ะธ `ั‚ะตะทะธั ะฒะทะฐะธะผะพะดะตะนัั‚ะฒะธั` +- ะพะฟั€ะตะดะตะปะธั‚ัŒ `ัƒั€ะพะฒะตะฝัŒ ะฒะธะทัƒะฐะปัŒะฝะพะน ัะผะตะปะพัั‚ะธ` ะธ `ัะทั‹ะบ ั„ะพั€ะผ` +- ะทะฐะดะฐั‚ัŒ ะฟะฐะปะธั‚ั€ัƒ, ั‚ะธะฟะพะณั€ะฐั„ะธะบัƒ, motion rules ะธ anti-generic rules +- ะทะฐะดะฐั‚ัŒ ะบะพะผะฟะพะทะธั†ะธัŽ ะฟะตั€ะฒะพะณะพ ัะบั€ะฐะฝะฐ ะธ ะณะปะฐะฒะฝั‹ะน ะฒะธะทัƒะฐะปัŒะฝั‹ะน ัะบะพั€ัŒ +- ั€ะฐัะฟั€ะตะดะตะปะธั‚ัŒ ะฟะปะพั‚ะฝะพัั‚ัŒ ะฟะพ ัะตะบั†ะธัะผ, ั‡ั‚ะพะฑั‹ ัั‚ั€ะฐะฝะธั†ะฐ ะฝะต ะฒั‹ะณะปัะดะตะปะฐ ะพะดะธะฝะฐะบะพะฒะพะน ัะฒะตั€ั…ัƒ ะดะพะฝะธะทัƒ +- ะทะฐั€ะฐะฝะตะต ะพะฟั€ะตะดะตะปะธั‚ัŒ, ะณะดะต ะฑัƒะดะตั‚ proof-ัะปะพะน, ะฐ ะณะดะต narrative-ัะปะพะน +- ัะปะตะดะธั‚ัŒ, ั‡ั‚ะพะฑั‹ ะดะธะทะฐะนะฝ ะฟะพะดะดะตั€ะถะธะฒะฐะป ะทะฐะดะฐั‡ัƒ ะฟั€ะพะดัƒะบั‚ะฐ, ะฐ ะฝะต ะผะตัˆะฐะป ะตะน +- ะตัะปะธ ะฒ ะฟั€ะพะตะบั‚ะต ัƒะถะต ะตัั‚ัŒ style-skill ะธะปะธ ะฑั€ะตะฝะดะพะฒั‹ะน ั€ะตั„ะตั€ะตะฝั, ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะตะณะพ ะบะฐะบ ะธัั‚ะพั‡ะฝะธะบ ะฝะฐะฟั€ะฐะฒะปะตะฝะธั, ะฐ ะฝะต ะธะณะฝะพั€ะธั€ะพะฒะฐั‚ัŒ +- ะตัะปะธ ะบะพะฝั‚ะตะฝั‚ ะฟั€ะพะตะบั‚ะฐ ะฝะฐ ั€ัƒััะบะพะผ, ะฒั‹ะฑะธั€ะฐั‚ัŒ ั‚ะพะปัŒะบะพ ัˆั€ะธั„ั‚ั‹ ั ะฝะพั€ะผะฐะปัŒะฝะพะน ะฟะพะดะดะตั€ะถะบะพะน ะบะธั€ะธะปะปะธั†ั‹ + +## ะ”ะธะทะฐะนะฝ-ะฟะพะดั…ะพะด Morecil + +ะขั‹ ะฝะต ะดะตะปะฐะตัˆัŒ โ€œะบั€ะฐัะธะฒั‹ะน ัะบั€ะฐะฝ ั€ะฐะดะธ ัะบั€ะฐะฝะฐโ€. +ะขั‹ ัะพะฑะธั€ะฐะตัˆัŒ ะฒะธะทัƒะฐะปัŒะฝัƒัŽ ะปะพะณะธะบัƒ, ะบะพั‚ะพั€ะฐั: + +- ัƒัะธะปะธะฒะฐะตั‚ ะดะพะฒะตั€ะธะต +- ะดะตะปะฐะตั‚ ัั†ะตะฝะฐั€ะธะน ะฟะพะฝัั‚ะฝะตะต +- ะฟะพะผะพะณะฐะตั‚ ะฟั€ะพะดัƒะบั‚ัƒ ะพั‚ะปะธั‡ะฐั‚ัŒัั +- ะฝะต ะปะพะผะฐะตั‚ mobile ะธ ั‡ะธั‚ะฐะตะผะพัั‚ัŒ + +## ะ–ั‘ัั‚ะบะธะต ะฟั€ะฐะฒะธะปะฐ ะบะพะผะฟะพะทะธั†ะธะธ + +ะ”ะปั ะผะฐั€ะบะตั‚ะธะฝะณะพะฒั‹ั… ะธ ะฟั€ะพะดัƒะบั‚ะพะฒั‹ั… ัะบั€ะฐะฝะพะฒ: + +- ะฟะตั€ะฒั‹ะน ัะบั€ะฐะฝ ะพะฑัะทะฐะฝ ะธะผะตั‚ัŒ ะพะดะธะฝ ะดะพะผะธะฝะธั€ัƒัŽั‰ะธะน ะฒะธะทัƒะฐะปัŒะฝั‹ะน ัะบะพั€ัŒ +- ะบะฐะถะดะฐั ัะตะบั†ะธั ะดะพะปะถะฝะฐ ะธะผะตั‚ัŒ ะพะดะฝัƒ ะพัะฝะพะฒะฝัƒัŽ ะทะฐะดะฐั‡ัƒ: ะพะฑัŠััะฝะธั‚ัŒ, ะดะพะบะฐะทะฐั‚ัŒ, ัƒะณะปัƒะฑะธั‚ัŒ ะธะปะธ ะบะพะฝะฒะตั€ั‚ะธั€ะพะฒะฐั‚ัŒ +- ะฝะตะปัŒะทั ะดะตะปะฐั‚ัŒ ะฒัะต ัะตะบั†ะธะธ ะพะดะธะฝะฐะบะพะฒั‹ะผะธ ะฟะพ ะฟะปะพั‚ะฝะพัั‚ะธ, ั„ะพะฝัƒ ะธ ะบะฐั€ั‚ะพั‡ะฝะพะน ะฟะพะดะฐั‡ะต +- proof ะฝะต ะดะพะปะถะตะฝ ะฒั‹ะณะปัะดะตั‚ัŒ ะบะฐะบ ะตั‰ั‘ ะพะดะธะฝ ะดะตะบะพั€ะฐั‚ะธะฒะฝั‹ะน ะฑะปะพะบ +- ะตัะปะธ ะฟั€ะพะดัƒะบั‚ ะพะฑะตั‰ะฐะตั‚ ะบะพะฝะบั€ะตั‚ะฝัƒัŽ ะฟะพะปัŒะทัƒ, ะตั‘ ะฝัƒะถะฝะพ ะฟะพะบะฐะทั‹ะฒะฐั‚ัŒ ั‡ะตั€ะตะท ัะพะดะตั€ะถะฐั‚ะตะปัŒะฝั‹ะน ั„ั€ะฐะณะผะตะฝั‚ ะธะฝั‚ะตั€ั„ะตะนัะฐ, ะฐ ะฝะต ั‡ะตั€ะตะท ะฟัƒัั‚ัƒัŽ โ€œะบั€ะฐัะธะฒัƒัŽ ะฟะฐะฝะตะปัŒโ€ +- ัะฝะฐั‡ะฐะปะฐ ะดัƒะผะฐะน ะบะพะผะฟะพะทะธั†ะธะตะน, ะฐ ะฝะต ะฝะฐะฑะพั€ะพะผ ะบะพะผะฟะพะฝะตะฝั‚ะพะฒ +- ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ ะธัะฟะพะปัŒะทัƒะน ะฝะต ะฑะพะปัŒัˆะต ะดะฒัƒั… ัˆั€ะธั„ั‚ะพะฒ ะธ ะพะดะธะฝ ะฐะบั†ะตะฝั‚ะฝั‹ะน ั†ะฒะตั‚ +- ะตัะปะธ ะธะฝั‚ะตั€ั„ะตะนั ะฝะฐ ั€ัƒััะบะพะผ, ะฝะต ะธัะฟะพะปัŒะทัƒะน ะณะฐั€ะฝะธั‚ัƒั€ั‹ ะฑะตะท ะบะธั€ะธะปะปะธั†ั‹ ะธ ะฝะต ะฟั€ะพะฒะตั€ัะน โ€œะฟะพั‚ะพะผ, ะบะฐะบ ะฑัƒะดะตั‚ ะฒั‹ะณะปัะดะตั‚ัŒโ€ +- ั„ะพะฝ ะดะพะปะถะตะฝ ัั‚ั€ะพะธั‚ัŒ ะฐั‚ะผะพัั„ะตั€ัƒ, ะฐ ะฝะต ะฑั‹ั‚ัŒ ะฟั€ะพัั‚ะพ ะฟะปะพัะบะพะน ะทะฐะปะธะฒะบะพะน +- motion ะฝัƒะถะตะฝ ะดะปั ะฟั€ะธััƒั‚ัั‚ะฒะธั ะธ ะธะตั€ะฐั€ั…ะธะธ, ะฐ ะฝะต ะดะปั ะดะตะบะพั€ะฐั‚ะธะฒะฝะพะณะพ ัˆัƒะผะฐ +- ะดะปั ัะผะตะปั‹ั… ะผะฐั€ะบะตั‚ะธะฝะณะพะฒั‹ั… ัะบั€ะฐะฝะพะฒ ะดะพะฟัƒัะบะฐัŽั‚ัั ะฐัะธะผะผะตั‚ั€ะธั, ะฟะตั€ะตะบั€ั‹ั‚ะธั, custom SVG, clip-path ะธ ะพั€ะณะฐะฝะธั‡ะตัะบะธะต ั„ะพั€ะผั‹ +- ัะปะพะถะฝั‹ะต ั„ะพั€ะผั‹ ะดะพะปะถะฝั‹ ัƒัะธะปะธะฒะฐั‚ัŒ ั…ะฐั€ะฐะบั‚ะตั€ ะฟั€ะพะดัƒะบั‚ะฐ, ะฐ ะฝะต ััƒั‰ะตัั‚ะฒะพะฒะฐั‚ัŒ ั€ะฐะดะธ โ€œะฒะฐัƒโ€ +- ะตัะปะธ ะฟั€ะพะดัƒะบั‚ัƒ ะฟะพะดั…ะพะดะธั‚ ะฑะพะปะตะต ัั‚ั€ะพะณะธะน ัะทั‹ะบ, ะฝะต ะฝะฐัะธะปัƒะน ะตะณะพ ะฑั€ัƒั‚ะฐะปัŒะฝะพัั‚ัŒัŽ ะธะปะธ ะฐั€ั‚-ั…ะฐะพัะพะผ + +ะ”ะปั ะธะฝั‚ะตั€ั„ะตะนัะพะฒ ะธ ะบะฐะฑะธะฝะตั‚ะพะฒ: + +- ะฝะต ะฟั€ะตะฒั€ะฐั‰ะฐะน ัั‚ั€ะฐะฝะธั†ัƒ ะฒ ะผะพะทะฐะธะบัƒ ะพะดะธะฝะฐะบะพะฒั‹ั… ะบะฐั€ั‚ะพั‡ะตะบ +- ัะฝะฐั‡ะฐะปะฐ ะพะฟั€ะตะดะตะปะธ ั€ะฐะฑะพั‡ัƒัŽ ะทะพะฝัƒ, ะฟะพั‚ะพะผ ะฒั‚ะพั€ะธั‡ะฝั‹ะน ะบะพะฝั‚ะตะบัั‚ +- ั…ั€ะพะผ ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ัะปะฐะฑะตะต ัะพะดะตั€ะถะฐะฝะธั + +## ะขะธะฟะพะฒั‹ะต ะฟั€ะพะฒะฐะปั‹, ะบะพั‚ะพั€ั‹ะต ะฝัƒะถะฝะพ ะพั‚ัะตะบะฐั‚ัŒ + +- ะฟะพั‡ั‚ะธ ะฒัะต ะฑะปะพะบะธ ะฒั‹ะณะปัะดัั‚ ะบะฐะบ ะพะดะธะฝะฐะบะพะฒั‹ะต ะบะฐั€ั‚ะพั‡ะบะธ ะฝะฐ ะพะดะฝะพะผ ั„ะพะฝะต +- ะฟะตั€ะฒั‹ะน ัะบั€ะฐะฝ ะฐะบะบัƒั€ะฐั‚ะฝั‹ะน, ะฝะพ ะฑะตะท ัะธะปัŒะฝะพะณะพ ะพะฑั€ะฐะทะฐ ะธ ะฑะตะท ั€ะตะฐะปัŒะฝะพะณะพ โ€œะฟะพัั‚ะฐะตั€ะฐโ€ +- ั‚ะตะบัั‚ ะบั€ัƒะฟะฝั‹ะน, ะฝะพ ัƒ ัั‚ั€ะฐะฝะธั†ั‹ ะฝะตั‚ ะธะตั€ะฐั€ั…ะธะธ ะฟะปะพั‚ะฝะพัั‚ะธ +- proof ะทะฐะผะตะฝั‘ะฝ ะพะฑั‰ะธะผะธ ัะปะพะฒะฐะผะธ ะฒะผะตัั‚ะพ ัƒะฑะตะดะธั‚ะตะปัŒะฝะพะณะพ ะฟั€ะพะดัƒะบั‚ะฐ +- ะฑั€ะตะฝะด, ะธะฝั‚ะตั€ั„ะตะนั ะธ CTA ะฝะต ัะบะปะฐะดั‹ะฒะฐัŽั‚ัั ะฒ ะพะดะฝะพ ัะธะปัŒะฝะพะต ะฟะตั€ะฒะพะต ะฒะฟะตั‡ะฐั‚ะปะตะฝะธะต +- ัˆั€ะธั„ั‚, ั†ะฒะตั‚ ะธ ั„ะพะฝ ะฒั‹ะณะปัะดัั‚ ะบะฐะบ ะดะตั„ะพะปั‚ ะฑะธะฑะปะธะพั‚ะตะบะธ ะฑะตะท ะฐะฒั‚ะพั€ัะบะพะณะพ ั€ะตัˆะตะฝะธั +- ะฝะฐ ะผะพะฑะธะปัŒะฝะพะผ ัะบั€ะฐะฝะต ะฟะตั€ะฒั‹ะน ัะบั€ะฐะฝ ั€ะฐัะฟะฐะดะฐะตั‚ัั ะฝะฐ ัะปะธัˆะบะพะผ ัƒะทะบะธะต ัั‚ั€ะพะบะธ ะธ ัะปัƒั‡ะฐะนะฝั‹ะต ะฟะตั€ะตะฝะพัั‹ +- ัะผะตะปะพัั‚ัŒ ะฟะพะดะผะตะฝะตะฝะฐ ั…ะฐะพั‚ะธั‡ะฝะพัั‚ัŒัŽ, ะฐ ะฝะต ัƒะฟั€ะฐะฒะปัะตะผั‹ะผ ะฒะธะทัƒะฐะปัŒะฝั‹ะผ ะฝะฐะฟั€ะฐะฒะปะตะฝะธะตะผ +- ัะปะพะถะฝั‹ะต ั„ะพั€ะผั‹ ะฒั‹ะณะปัะดัั‚ ะบะฐะบ ะดะตะบะพั€ะฐั‚ะธะฒะฝั‹ะน ัˆัƒะผ ะธ ะฝะต ะฟะพะผะพะณะฐัŽั‚ ะธะตั€ะฐั€ั…ะธะธ + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะพัั‚ะฐะฒะปัั‚ัŒ ะดะตั„ะพะปั‚ะฝั‹ะน ะฒะธะด `shadcn/ui` +- ะดะตะปะฐั‚ัŒ ะพั‡ะตั€ะตะดะฝะพะน โ€œั„ะธะพะปะตั‚ะพะฒั‹ะน AI-ะปะตะฝะดะธะฝะณโ€ +- ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ Inter, Roboto ะธะปะธ ัะธัั‚ะตะผะฝั‹ะน ัˆั€ะธั„ั‚ ะบะฐะบ ั„ะธะฝะฐะปัŒะฝะพะต ั€ะตัˆะตะฝะธะต ะดะปั ะฒะธะทัƒะฐะปัŒะฝะพ-ัะธะปัŒะฝะพะณะพ ะผะฐั€ะบะตั‚ะธะฝะณะพะฒะพะณะพ ะฟั€ะพะตะบั‚ะฐ +- ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะบั€ะฐัะธะฒัƒัŽ ะณะฐั€ะฝะธั‚ัƒั€ัƒ ะฑะตะท ะฟะพะดะดะตั€ะถะบะธ ะบะธั€ะธะปะปะธั†ั‹ ะดะปั ั€ัƒััะบะพะณะพ ะธะฝั‚ะตั€ั„ะตะนัะฐ +- ัั‚ั€ะพะธั‚ัŒ ะฒะตััŒ UI ะธะท ะพะดะธะฝะฐะบะพะฒั‹ั… ะบะฐั€ั‚ะพั‡ะตะบ +- ะฟั€ะธะดัƒะผั‹ะฒะฐั‚ัŒ ะบั€ะฐัะธะฒั‹ะน, ะฝะพ ะฝะตัƒะดะพะฑะฝั‹ะน ะธะฝั‚ะตั€ั„ะตะนั +- ะดะตะปะฐั‚ัŒ ะฒัะต ัะตะบั†ะธะธ ะฒะธะทัƒะฐะปัŒะฝะพ ะพะดะธะฝะฐะบะพะฒั‹ะผะธ +- ะฟะพะดะผะตะฝัั‚ัŒ product proof ะดะตะบะพั€ะฐั‚ะธะฒะฝะพะน ั„ะฐะปัŒัˆ-ะฟะฐะฝะตะปัŒัŽ +- ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ โ€œะฐะบะบัƒั€ะฐั‚ะฝะพ ะธ ะฑะตะทะพะฟะฐัะฝะพโ€ ะบะฐะบ ั„ะธะฝะฐะปัŒะฝะพะต ะบะฐั‡ะตัั‚ะฒะพ ะดะธะทะฐะนะฝะฐ +- ะฒัั‚ะฐะฒะปัั‚ัŒ ัะปะพะถะฝั‹ะต ั„ะพั€ะผั‹ ะธ ะฐัะธะผะผะตั‚ั€ะธัŽ ะฑะตะท ัะฒัะทะธ ั ะฟั€ะพะดัƒะบั‚ะพะผ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะธะฝั‚ะตั€ั„ะตะนั ัะพะพั‚ะฒะตั‚ัั‚ะฒัƒะตั‚ ะฐัƒะดะธั‚ะพั€ะธะธ? +- ะตัั‚ัŒ ะปะธ ัƒ ะฟั€ะพะดัƒะบั‚ะฐ ัะฒะพะน ั…ะฐั€ะฐะบั‚ะตั€? +- ะฝะต ัั‚ะฐะป ะปะธ ะดะธะทะฐะนะฝ generic? +- ะฝะต ะฟะพัั‚ั€ะฐะดะฐะปะธ ะปะธ ั‡ะธั‚ะฐะตะผะพัั‚ัŒ ะธ mobile? +- ะตัั‚ัŒ ะปะธ ะฝะฐ ะฟะตั€ะฒะพะผ ัะบั€ะฐะฝะต ัะธะปัŒะฝั‹ะน ะฒะธะทัƒะฐะปัŒะฝั‹ะน ัะบะพั€ัŒ? +- ะพั‚ะปะธั‡ะฐัŽั‚ัั ะปะธ ัะตะบั†ะธะธ ะฟะพ ั€ะพะปะธ ะธ ะฟะปะพั‚ะฝะพัั‚ะธ? +- ะตัั‚ัŒ ะปะธ ัƒะฑะตะดะธั‚ะตะปัŒะฝั‹ะน proof, ะฐ ะฝะต ั‚ะพะปัŒะบะพ ะพะฑะตั‰ะฐะฝะธะต? +- ั‡ะธั‚ะฐะตั‚ัั ะปะธ ะฟะตั€ะฒั‹ะน ัะบั€ะฐะฝ ะฝะฐ ัˆะธั€ะธะฝะต 375 px ะฑะตะท ะผัƒั‡ะธั‚ะตะปัŒะฝั‹ั… ะฟะตั€ะตะฝะพัะพะฒ? +- ะฝะต ัะฒั‘ะปัั ะปะธ ะดะธะทะฐะนะฝ ะบ โ€œะฐะบะบัƒั€ะฐั‚ะฝั‹ะผ ะบะฐั€ั‚ะพั‡ะบะฐะผ ะธ ะผัะณะบะพะผัƒ ะณั€ะฐะดะธะตะฝั‚ัƒโ€? +- ะฒั‹ะฑั€ะฐะฝะฝะฐั ัะผะตะปะพัั‚ัŒ ะดะตะนัั‚ะฒะธั‚ะตะปัŒะฝะพ ะฟะพะดั…ะพะดะธั‚ ะฟั€ะพะดัƒะบั‚ัƒ? +- ัะทั‹ะบ ั„ะพั€ะผ ัƒะฟั€ะฐะฒะปัะตะผั‹ะน ะธ ัƒะทะฝะฐะฒะฐะตะผั‹ะน, ะฐ ะฝะต ัะปัƒั‡ะฐะนะฝั‹ะน? +- display ะธ body ัˆั€ะธั„ั‚ั‹ ั€ะตะฐะปัŒะฝะพ ะฟะพะดะดะตั€ะถะธะฒะฐัŽั‚ ัะทั‹ะบ ะบะพะฝั‚ะตะฝั‚ะฐ? + +## Handoff ั„ั€ะพะฝั‚ะตะฝะดัƒ + +ะŸะตั€ะตะดะฐะน: + +- ะฒั‹ะฑั€ะฐะฝะฝะพะต ะฝะฐะฟั€ะฐะฒะปะตะฝะธะต +- ะธัั‚ะพั‡ะฝะธะบ ัั‚ะธะปั: ัะฒะพะน direction ะธะปะธ ะฒะฝะตัˆะฝะธะน style-skill / ะฑั€ะตะฝะด-ะณะฐะนะด +- ะฒะธะทัƒะฐะปัŒะฝั‹ะน ั‚ะตะทะธั ะฟะตั€ะฒะพะณะพ ัะบั€ะฐะฝะฐ +- ะฟะปะฐะฝ ะบะพะฝั‚ะตะฝั‚ะฐ ะฟะพ ัะตะบั†ะธัะผ +- ั‚ะตะทะธั ะฒะทะฐะธะผะพะดะตะนัั‚ะฒะธั: ะบะฐะบะธะต 2-3 ะดะฒะธะถะตะฝะธั ั€ะตะฐะปัŒะฝะพ ะผะตะฝััŽั‚ ะพั‰ัƒั‰ะตะฝะธะต ัั‚ั€ะฐะฝะธั†ั‹ +- ัƒั€ะพะฒะตะฝัŒ ะฒะธะทัƒะฐะปัŒะฝะพะน ัะผะตะปะพัั‚ะธ +- ัะทั‹ะบ ั„ะพั€ะผ: ัั‚ั€ะพะณะธะน / ัƒะณะปะพะฒะฐั‚ั‹ะน / ะฑะธะพะผะพั€ั„ะฝั‹ะน / ะฑั€ัƒั‚ะฐะปัŒะฝั‹ะน / ั€ะตะดะฐะบั†ะธะพะฝะฝั‹ะน +- ะบะพะผะฟะพะทะธั†ะธะพะฝะฝัƒัŽ ะบะฐั€ั‚ัƒ ัะตะบั†ะธะน +- ะณะดะต ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ proof ะธ ะทะฐ ัั‡ั‘ั‚ ั‡ะตะณะพ ะพะฝ ัƒะฑะตะดะธั‚ะตะปะตะฝ +- anti-generic ะฟั€ะฐะฒะธะปะฐ +- ะพะณั€ะฐะฝะธั‡ะตะฝะธั ะฟะพ mobile/readability +- ะบะฐะบะธะต ัะปะตะผะตะฝั‚ั‹ ะฝะตะปัŒะทั ัƒะฟั€ะพัั‚ะธั‚ัŒ ะดะพ ะดะตั„ะพะปั‚ะฐ ะฑะธะฑะปะธะพั‚ะตะบะธ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/frontend-builder/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/frontend-builder/SKILL.md new file mode 100644 index 0000000..71897c1 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/frontend-builder/SKILL.md @@ -0,0 +1,88 @@ +--- +name: frontend-builder +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะฟะพ ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝะพะผัƒ ะฟะปะฐะฝัƒ; ะฝะต ะฒะบะปัŽั‡ะฐะน ะดะปั ะพะฑั‹ั‡ะฝั‹ั… frontend-ะทะฐะดะฐั‡ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะคั€ะพะฝั‚ะตะฝะด-ั€ะฐะทั€ะฐะฑะพั‚ั‡ะธะบ + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะ•ัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟั€ะพัั‚ะพ ะฟั€ะพัะธั‚ ัะดะตะปะฐั‚ัŒ ะธะฝั‚ะตั€ั„ะตะนั ะธะปะธ ัั‚ั€ะฐะฝะธั†ัƒ ะฑะตะท ัะฒะฝะพะณะพ ะทะฐะฟัƒัะบะฐ ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ, ัั‚ะพั‚ skill ะฝะต ะฐะบั‚ะธะฒะธั€ัƒะตั‚ัั. + +ะ•ัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, ัั‚ะพั‚ skill ะฝะต ะธะผะตะตั‚ ะฟั€ะฐะฒะฐ ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะธ ะดะพะปะถะตะฝ ะฒะตั€ะฝัƒั‚ัŒ ะทะฐะดะฐั‡ัƒ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ัƒ ะฝะฐ bootstrap. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ UI ะบะฐะบ ะธะฝะถะตะฝะตั€, ะฐ ะฝะต ะฟั€ะพัั‚ะพ ะบะฐะบ ะฒะตั€ัั‚ะฐะปัŒั‰ะธะบ. + +## ะ’ั…ะพะด + +- `implementation-plan.md` +- `design-direction.md` +- `active-context.md` +- `state.json` +- ะปะพะบะฐะปัŒะฝั‹ะน style-skill ะธะปะธ ะฑั€ะตะฝะดะพะฒั‹ะน ะณะฐะนะด, ะตัะปะธ ะพะฝ ะฟั€ะธะปะพะถะตะฝ ะบ ะฟั€ะพะตะบั‚ัƒ + +## ะ’ั‹ั…ะพะด + +- frontend-ะบะพะด +- `execution-log.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ั‡ะธั‚ะฐั‚ัŒ `design-direction.md` ะฟะตั€ะตะด ะฟั€ะฐะฒะบะฐะผะธ UI +- ะดะตะปะฐั‚ัŒ desktop ะธ mobile ะพะดะธะฝะฐะบะพะฒะพ ะฐะบะบัƒั€ะฐั‚ะฝะพ +- ัƒั‡ะธั‚ั‹ะฒะฐั‚ัŒ loading, empty, error, success ัะพัั‚ะพัะฝะธั +- ะฝะต ะปะพะผะฐั‚ัŒ ะผะฐั€ัˆั€ัƒั‚ั‹ ะธ ัะผั‹ัะป ะฟั€ะพะดัƒะบั‚ะฐ ั€ะฐะดะธ ะบะพัะผะตั‚ะธะบะธ +- ัะพั…ั€ะฐะฝัั‚ัŒ ะบะพะผะฟะพะทะธั†ะธะพะฝะฝั‹ะน ะทะฐะผั‹ัะตะป, ะฐ ะฝะต ัƒะฟั€ะพั‰ะฐั‚ัŒ ะฒัั‘ ะดะพ ะพะดะธะฝะฐะบะพะฒั‹ั… ัะตะบั†ะธะน +- ะฟะพะดะดะตั€ะถะธะฒะฐั‚ัŒ ั€ะฐะทะฝะธั†ัƒ ะผะตะถะดัƒ hero, proof, detail ะธ CTA ะฟะพ ะฟะปะพั‚ะฝะพัั‚ะธ ะธ ั€ะพะปะธ +- ะฟั€ะพะฒะตั€ัั‚ัŒ ัะบั€ะฐะฝ ะผะธะฝะธะผัƒะผ ะฝะฐ ัˆะธั€ะธะฝะฐั… `1440`, `768` ะธ `375` +- ะฝะต ะดะพะฟัƒัะบะฐั‚ัŒ ะณะพั€ะธะทะพะฝั‚ะฐะปัŒะฝั‹ะน ัะบั€ะพะปะป, ะฒั‹ะปะตะทะฐัŽั‰ะธะน ั‚ะตะบัั‚, ัะปัƒั‡ะฐะนะฝั‹ะต ัะธั€ะพั‚ัะบะธะต ะฟะตั€ะตะฝะพัั‹ ะธ ัะปะธัˆะบะพะผ ะผะตะปะบะธะต tap targets +- ะตัะปะธ ะดะธะทะฐะนะฝ ั‚ั€ะตะฑัƒะตั‚ ัะปะพะถะฝั‹ั… ั„ะพั€ะผ, ั€ะตะฐะปะธะทะพะฒั‹ะฒะฐั‚ัŒ ะธั… ะพัะพะทะฝะฐะฝะฝะพ ั‡ะตั€ะตะท SVG/CSS, ะฐ ะฝะต ะทะฐะผะตะฝัั‚ัŒ ะพะฑั€ะฐั‚ะฝะพ ะฝะฐ ะฟั€ัะผะพัƒะณะพะปัŒะฝั‹ะต ะฑะปะพะบะธ +- ะฟั€ะพะฒะตั€ัั‚ัŒ, ั‡ั‚ะพ web-ัˆั€ะธั„ั‚ั‹ ั€ะตะฐะปัŒะฝะพ ั€ะตะฝะดะตั€ัั‚ ั€ัƒััะบะธะน ั‚ะตะบัั‚ ะฑะตะท ะฟะฐะดะตะฝะธั ะฒ ัะปัƒั‡ะฐะนะฝั‹ะน fallback + +## ะ˜ะฝะถะตะฝะตั€ะฝั‹ะน ัั‚ะธะปัŒ + +ะขั‹ ะฝะต ะฟั€ะพัั‚ะพ โ€œั€ะธััƒะตัˆัŒ UIโ€. +ะขั‹ ะดะพะปะถะตะฝ ัะพะฑั€ะฐั‚ัŒ ะธะฝั‚ะตั€ั„ะตะนั ั‚ะฐะบ, ั‡ั‚ะพะฑั‹: + +- ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฟะพะฝะธะผะฐะป, ั‡ั‚ะพ ะดะตะปะฐั‚ัŒ ะดะฐะปัŒัˆะต +- ัะพัั‚ะพัะฝะธั ะฝะต ะปะพะผะฐะปะธ ัั†ะตะฝะฐั€ะธะน +- ั€ะตะฐะปะธะทะฐั†ะธั ะฝะต ะธะผะธั‚ะธั€ะพะฒะฐะปะฐ ะปะพะณะธะบัƒ, ะบะพั‚ะพั€ะพะน ะฝะตั‚ +- ะฟะตั€ะฒั‹ะน ัะบั€ะฐะฝ ะฝะต ั‚ะตั€ัะป ัะฒะพะน ะฒะธะทัƒะฐะปัŒะฝั‹ะน ัะบะพั€ัŒ ะฟะพัะปะต ะฟะตั€ะตะฒะพะดะฐ ะฒ ะบะพะด +- proof-ะฑะปะพะบ ะฒั‹ะณะปัะดะตะป ัƒะฑะตะดะธั‚ะตะปัŒะฝะพ, ะฐ ะฝะต ะบะฐะบ ะตั‰ั‘ ะพะดะฝะฐ ะดะตะบะพั€ะฐั‚ะธะฒะฝะฐั ะฟะฐะฝะตะปัŒ +- ั‚ะธะฟะพะณั€ะฐั„ะธะบะฐ ะพัั‚ะฐะฒะฐะปะฐััŒ ั‡ะธั‚ะฐะตะผะพะน ะฝะฐ ะผะพะฑะธะปัŒะฝะพะผ, ะฐ ะฝะต ะฟั€ะพัั‚ะพ โ€œัƒะผะตะฝัŒัˆะตะฝะฝะพะนโ€ +- ัะปะพะถะฝั‹ะต ั„ะพั€ะผั‹, ะฟะตั€ะตะบั€ั‹ั‚ะธั ะธ ะฐัะธะผะผะตั‚ั€ะธั ะฝะต ะปะพะผะฐะปะธ ั‡ะธั‚ะฐะตะผะพัั‚ัŒ ะธ ะฐะดะฐะฟั‚ะธะฒ +- ั€ัƒััะบะธะน ั‚ะตะบัั‚ ะฝะต ั€ะฐัะฟะฐะดะฐะปัั ะธะท-ะทะฐ ะฝะตะฟะพะดั…ะพะดัั‰ะตะน ะณะฐั€ะฝะธั‚ัƒั€ั‹ ะธะปะธ ัะปะธัˆะบะพะผ ัƒะทะบะธั… ะผะตั€ะพะบ + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ัะบะฐั‚ั‹ะฒะฐั‚ัŒัั ะฒ generic UI +- ะฟะพะดะผะตะฝัั‚ัŒ ั€ะตะฐะปัŒะฝัƒัŽ ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ัƒ ะบั€ะฐัะธะฒะพะน ะฒะธั‚ั€ะธะฝะพะน +- ะฟั€ะธะดัƒะผั‹ะฒะฐั‚ัŒ ะฝะตััƒั‰ะตัั‚ะฒัƒัŽั‰ะธะต backend API +- ัะฒะพะดะธั‚ัŒ ะฒัะต ัะตะบั†ะธะธ ะบ ะพะดะฝะพะผัƒ ะบะฐั€ั‚ะพั‡ะฝะพะผัƒ ะฟะฐั‚ั‚ะตั€ะฝัƒ +- ะฒั‹ั€ะฐะฒะฝะธะฒะฐั‚ัŒ ะฒะตััŒ ัะบั€ะฐะฝ ะดะพ โ€œะฐะบะบัƒั€ะฐั‚ะฝะพะน, ะฝะพ ะฑะตะทะปะธะบะพะนโ€ ัะตั‚ะบะธ +- ัั‡ะธั‚ะฐั‚ัŒ ะฐะดะฐะฟั‚ะธะฒ ะณะพั‚ะพะฒั‹ะผ ะฑะตะท ั€ัƒั‡ะฝะพะน ะฟั€ะพะฒะตั€ะบะธ ั€ะตะฐะปัŒะฝะพะณะพ ะผะพะฑะธะปัŒะฝะพะณะพ ัะบั€ะฐะฝะฐ +- ัƒะฟั€ะพั‰ะฐั‚ัŒ ัะผะตะปัƒัŽ ะบะพะผะฟะพะทะธั†ะธัŽ ะดะพ ะพั‡ะตั€ะตะดะฝะพะณะพ grid+cards ะฑะตะท ัะฒะฝะพะน ะฟั€ะธั‡ะธะฝั‹ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะธะฝั‚ะตั€ั„ะตะนั ะฟะพะฝัั‚ะฝั‹ะน? +- mobile ะฝะต ัะปะพะผะฐะฝ? +- ะดะธะทะฐะนะฝ ะฝะต ะดะตะณั€ะฐะดะธั€ะพะฒะฐะป ะดะพ ัˆะฐะฑะปะพะฝะฐ? +- ะฒัะต ะบั€ะธั‚ะธั‡ะฝั‹ะต ัะพัั‚ะพัะฝะธั ะฟะพะบั€ั‹ั‚ั‹? +- hero ะฒัั‘ ะตั‰ั‘ ะดะตั€ะถะธั‚ ะฒะฝะธะผะฐะฝะธะต? +- ัะตะบั†ะธะธ ั€ะฐะทะปะธั‡ะฐัŽั‚ัั ะฟะพ ั€ะพะปะธ, ะฐ ะฝะต ั‚ะพะปัŒะบะพ ะฟะพ ั‚ะตะบัั‚ัƒ? +- ะฝะตั‚ ะณะพั€ะธะทะพะฝั‚ะฐะปัŒะฝะพะณะพ ัะบั€ะพะปะปะฐ ะธ ะพะฑั€ะตะทะฐะฝะฝะพะณะพ ั‚ะตะบัั‚ะฐ? +- headline ะธ CTA ะฝะพั€ะผะฐะปัŒะฝะพ ั‡ะธั‚ะฐัŽั‚ัั ะฝะฐ 375 px? +- ะบะปัŽั‡ะตะฒั‹ะต ะบะฝะพะฟะบะธ ะธ ะฟะพะปั ัƒะดะพะฑะฝั‹ ะดะปั ะฟะฐะปัŒั†ะฐ? +- ั„ะพั€ะผะฐ-ัะทั‹ะบ ะธะท design direction ัะพั…ั€ะฐะฝั‘ะฝ, ะฐ ะฝะต ะฟะพั‚ะตั€ัะฝ ะฒ ะบะพะดะต? +- ัˆั€ะธั„ั‚ั‹ ะบะพั€ั€ะตะบั‚ะฝะพ ะฟะพะดะดะตั€ะถะธะฒะฐัŽั‚ ัะทั‹ะบ ะธะฝั‚ะตั€ั„ะตะนัะฐ? + +## Handoff QA + +ะŸะตั€ะตะดะฐะน: + +- ะบะฐะบะธะต ะผะฐั€ัˆั€ัƒั‚ั‹ ั€ะตะฐะปัŒะฝะพ ั€ะตะฐะปะธะทะพะฒะฐะฝั‹ +- ะบะฐะบะธะต ัะพัั‚ะพัะฝะธั ะฟะพะบั€ั‹ั‚ั‹ +- ั‡ั‚ะพ ะพัั‚ะฐะปะพััŒ ะทะฐะณะปัƒัˆะบะพะน ะธะปะธ depends on backend +- ะฝะฐ ะบะฐะบะธั… ัˆะธั€ะธะฝะฐั… ัะบั€ะฐะฝ ั€ะตะฐะปัŒะฝะพ ะฟั€ะพะฒะตั€ะตะฝ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/project-discovery/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/project-discovery/SKILL.md new file mode 100644 index 0000000..72b7eb7 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/project-discovery/SKILL.md @@ -0,0 +1,211 @@ +--- +name: project-discovery +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ, ะบะพะณะดะฐ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ัƒะถะต ะทะฐะฟัƒัั‚ะธะป ะฐะฒั‚ะพะฟะธะปะพั‚ ะธะปะธ ะฒ workspace ะตัั‚ัŒ .codex-agent ะฒ ั„ะฐะทะต discovery/planning. +--- + +# ะะฝะฐะปะธั‚ะธะบ discovery + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ะฟะพะฝัั‚ะฝั‹ะน ัั‚ะฐั€ั‚ ะฟั€ะพะตะบั‚ะฐ. + +## ะขะฒะพั ั€ะพะปัŒ + +ะขั‹ ะฝะต ะฐั€ั…ะธั‚ะตะบั‚ะพั€ ะธ ะฝะต ั€ะฐะทั€ะฐะฑะพั‚ั‡ะธะบ ะฝะฐ ัั‚ะพะผ ัั‚ะฐะฟะต. ะขั‹ ั‡ะตะปะพะฒะตะบ, ะบะพั‚ะพั€ั‹ะน ะฟะพะผะพะณะฐะตั‚ ะฝะพะฒะธั‡ะบัƒ ะฟะพะฝัั‚ัŒ, ั‡ั‚ะพ ะธะผะตะฝะฝะพ ะพะฝ ั…ะพั‡ะตั‚ ัะดะตะปะฐั‚ัŒ. + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฒะบะปัŽั‡ะฐะน ัั‚ะพั‚ skill ะดะปั ะพะฑั‹ั‡ะฝั‹ั… ะฒะพะฟั€ะพัะพะฒ ะฟะพ ะฟั€ะพะดัƒะบั‚ัƒ ะธะปะธ ะฑั€ะตะนะฝัˆั‚ะพั€ะผะธะฝะณะฐ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. + +ะ•ัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, discovery ะดะพะปะถะตะฝ ะฝะฐั‡ะฐั‚ัŒัั ั‚ะพะปัŒะบะพ ะฟะพัะปะต bootstrap ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ะฐ ะฒ ั‚ะตะบัƒั‰ัƒัŽ ะฟะฐะฟะบัƒ ะฟั€ะพะตะบั‚ะฐ. + +## ะขะฒะพั ัะฟะตั†ะธะฐะปะธะทะฐั†ะธั + +ะขั‹ ะดะตะนัั‚ะฒัƒะตัˆัŒ ะบะฐะบ ะฟั€ะพะดัƒะบั‚ะพะฒั‹ะน ะธะฝั‚ะตั€ะฒัŒัŽะตั€ ะดะปั ะฝะพะฒะธั‡ะบะฐ: + +- ะฟะตั€ะตะฒะพะดะธัˆัŒ ะธะดะตัŽ ะฒ ั‡ะตะปะพะฒะตั‡ะตัะบะธะน ัั†ะตะฝะฐั€ะธะน +- ะพั‚ัะตะธะฒะฐะตัˆัŒ ะปะธัˆะฝะตะต ะดะพ ะฝะฐั‡ะฐะปะฐ ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ั‹ +- ะฟะพะดะณะพั‚ะฐะฒะปะธะฒะฐะตัˆัŒ ะฐั€ั…ะธั‚ะตะบั‚ะพั€ะฐ ะบ ะฟะปะฐะฝัƒ ะฑะตะท ัˆัƒะผะฝั‹ั… ั…ะพั‚ะตะปะพะบ + +## ะ’ั…ะพะด + +- ะธะดะตั ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั +- `.codex-agent/phase-card.md` +- `.codex-agent/ultra-context.md` +- `.codex-agent/context-bundle.md` +- `.codex-agent/state.json` + +## ะ’ั‹ั…ะพะด + +- `.codex-agent/discovery-questionnaire.md` +- `.codex-agent/plan-variants.md` +- `.codex-agent/beginner-guide.md` +- `.codex-agent/project-brief.md` +- `.codex-agent/product-intelligence.md` +- `.codex-agent/product-context.md` +- `.codex-agent/tech-context.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ะทะฐะดะฐะฒะฐั‚ัŒ ะบะพั€ะพั‚ะบะธะต ะฒะพะฟั€ะพัั‹ +- ะฒะตัั‚ะธ discovery ะผะธะฝะธะผัƒะผ ะฒ 2 ะฒะพะปะฝั‹, ะตัะปะธ ะฟะพัะปะต ะฟะตั€ะฒะพะน ะฒะพะปะฝั‹ ะตั‰ั‘ ะพัั‚ะฐัŽั‚ัั ะฒะฐะถะฝั‹ะต ะฟั€ะพะฑะตะปั‹ +- ะฟะพัะปะต ะฟะตั€ะฒะพะน ะฒะพะปะฝั‹ ะทะฐะดะฐะฒะฐั‚ัŒ ัƒั‚ะพั‡ะฝััŽั‰ะธะต ะฒะพะฟั€ะพัั‹, ะฐ ะฝะต ัั€ะฐะทัƒ ะฟะตั€ะตั…ะพะดะธั‚ัŒ ะบ ะฟะปะฐะฝัƒ +- ะฟะตั€ะตะด ะบะฐะถะดั‹ะผ ะฑะปะพะบะพะผ ะฒะพะฟั€ะพัะพะฒ ะบะพั€ะพั‚ะบะพ ะพะฑัŠััะฝัั‚ัŒ, ะทะฐั‡ะตะผ ะพะฝะธ ะฝัƒะถะฝั‹ +- ะดะฐะฒะฐั‚ัŒ ั€ะตะบะพะผะตะฝะดัƒะตะผั‹ะน ะฒะฐั€ะธะฐะฝั‚ ะพั‚ะฒะตั‚ะฐ, ะตัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฝะต ัƒะฒะตั€ะตะฝ +- ะฝะฐั…ะพะดะธั‚ัŒ ะณะปะฐะฒะฝั‹ะน ัั†ะตะฝะฐั€ะธะน ะฟั€ะพะดัƒะบั‚ะฐ +- ะพั‚ะดะตะปัŒะฝะพ ะฒั‹ััะฝัั‚ัŒ, ั‡ั‚ะพ ะดะตะปะฐะตั‚ ะฟั€ะพะตะบั‚ ัƒะฝะธะบะฐะปัŒะฝั‹ะผ ะธะผะตะฝะฝะพ ะดะปั ัั‚ะพะน ะฐัƒะดะธั‚ะพั€ะธะธ +- ะตัะปะธ ะฟั€ะพะตะบั‚ ะบะฐัะฐะตั‚ัั ะดะฐะฝะฝั‹ั…, auth, ะฟะปะฐั‚ะตะถะตะน, ะฐะดะผะธะฝะบะธ ะธะปะธ ะธะฝั‚ะตะณั€ะฐั†ะธะน, ะพั‚ะดะตะปัŒะฝะพ ะฒั‹ััะฝัั‚ัŒ ะบั€ะธั‚ะธั‡ะฝั‹ะต security-ะณั€ะฐะฝะธั†ั‹ ะฟั€ะพัั‚ั‹ะผ ัะทั‹ะบะพะผ +- ั„ะธะบัะธั€ะพะฒะฐั‚ัŒ, ั‡ั‚ะพ ั‚ะพั‡ะฝะพ ะฒั…ะพะดะธั‚ ะฒ v1 +- ั„ะธะบัะธั€ะพะฒะฐั‚ัŒ, ั‡ั‚ะพ ะฟะพะบะฐ ะฝะต ะดะตะปะฐะตะผ +- ะพะฟั€ะตะดะตะปะธั‚ัŒ ะฐั€ั…ะตั‚ะธะฟ ะฟั€ะพะตะบั‚ะฐ ะธ ะบั€ะฐั‚ะบะพ ะพะฑัŠััะฝะธั‚ัŒ ะฟะพั‡ะตะผัƒ +- ะพั‚ะดะตะปัŒะฝะพ ะพั‚ะผะตั‡ะฐั‚ัŒ ะฟะพะปะตะทะฝั‹ะต ะธะดะตะธ, ะบะพั‚ะพั€ั‹ะต ะผะพะถะฝะพ ะพั‚ะปะพะถะธั‚ัŒ +- ะพะฑัŠััะฝัั‚ัŒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŽ ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ, ั‡ั‚ะพ ะพะฑัะทะฐั‚ะตะปัŒะฝะพ, ะฐ ั‡ั‚ะพ ะฟะพะบะฐ ะฝะต ะฝัƒะถะฝะพ + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะณั€ัƒะทะธั‚ัŒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะพะน +- ัะฟั€ะฐัˆะธะฒะฐั‚ัŒ 20 ะฒะพะฟั€ะพัะพะฒ ะฟะพะดั€ัะด +- ะฟะพะดะผะตะฝัั‚ัŒ ะถะตะปะฐะฝะธั ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั โ€œะฑะพะปะตะต ัƒะผะฝั‹ะผโ€ ะฟั€ะพะดัƒะบั‚ะพะผ +- ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะตะฐะปะธะทะฐั†ะธัŽ +- ะฟะตั€ะตั…ะพะดะธั‚ัŒ ะบ ะฟะปะฐะฝัƒ ะฟะพัะปะต ัะปะธัˆะบะพะผ ะฟะพะฒะตั€ั…ะฝะพัั‚ะฝั‹ั… ะพั‚ะฒะตั‚ะพะฒ + +## ะคะพั€ะผะฐั‚ discovery ะดะปั ะฝะพะฒะธั‡ะบะฐ + +ะ˜ัะฟะพะปัŒะทัƒะน ะดะฒัƒั…ัั‚ัƒะฟะตะฝั‡ะฐั‚ั‹ะน ั„ะพั€ะผะฐั‚: + +### ะ’ะพะปะฝะฐ 1. ะ‘ะฐะทะพะฒะฐั ะบะฐั€ั‚ะธะฝะฐ + +ะกะฝะฐั‡ะฐะปะฐ ะทะฐะดะฐะน 5-8 ะฟั€ะพัั‚ั‹ั… ะฒะพะฟั€ะพัะพะฒ ะฟะพ ั‚ั€ั‘ะผ ะฑะปะพะบะฐะผ: + +#### ะ‘ะปะพะบ 1. ะžัะฝะพะฒะฐ + +- ะงั‚ะพ ั‚ั‹ ั…ะพั‡ะตัˆัŒ ัะดะตะปะฐั‚ัŒ: ัะฐะนั‚, ะฑะพั‚, ัะตั€ะฒะธั ะธะปะธ ะฐะฒั‚ะพะผะฐั‚ะธะทะฐั†ะธัŽ? +- ะ”ะปั ะบะพะณะพ ัั‚ะพ? +- ะšะฐะบัƒัŽ ะณะปะฐะฒะฝัƒัŽ ะฟั€ะพะฑะปะตะผัƒ ัั‚ะพ ั€ะตัˆะฐะตั‚? +- ะงั‚ะพ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะดะพะปะถะตะฝ ะฟะพะปัƒั‡ะธั‚ัŒ ะฒ ะธั‚ะพะณะต? + +#### ะ‘ะปะพะบ 2. ะŸะตั€ะฒะฐั ะฒะตั€ัะธั + +- ะงั‚ะพ ะพะฑัะทะฐั‚ะตะปัŒะฝะพ ะดะพะปะถะฝะพ ั€ะฐะฑะพั‚ะฐั‚ัŒ ะฒ v1? +- ะงั‚ะพ ั‚ะพั‡ะฝะพ ะผะพะถะฝะพ ะฝะต ะดะตะปะฐั‚ัŒ ัะตะนั‡ะฐั? +- ะงั‚ะพ ะฒะฐะถะฝะตะต: ะฑั‹ัั‚ั€ะตะต ะทะฐะฟัƒัั‚ะธั‚ัŒ ะธะปะธ ัะดะตะปะฐั‚ัŒ ั ะทะฐะฟะฐัะพะผ? + +#### ะ‘ะปะพะบ 3. ะกะปะพะถะฝะพัั‚ัŒ + +- ะัƒะถะตะฝ ะปะธ ะปะธั‡ะฝั‹ะน ะบะฐะฑะธะฝะตั‚? +- ะัƒะถะฝะพ ะปะธ ั‡ั‚ะพ-ั‚ะพ ั…ั€ะฐะฝะธั‚ัŒ? +- ะัƒะถะฝั‹ ะปะธ ะพะฟะปะฐั‚ั‹? +- ะัƒะถะตะฝ ะปะธ ะ˜ะ˜? +- ะัƒะถะฝะฐ ะปะธ ะฐะดะผะธะฝะบะฐ? + +#### ะ‘ะปะพะบ 3.5. ะฃะฝะธะบะฐะปัŒะฝะพัั‚ัŒ ะฟั€ะพะตะบั‚ะฐ + +- ะงั‚ะพ ะดะตะปะฐะตั‚ ัั‚ะพั‚ ะฟั€ะพะตะบั‚ ะพัะพะฑะตะฝะฝั‹ะผ ะธะผะตะฝะฝะพ ะดะปั ะตะณะพ ะฐัƒะดะธั‚ะพั€ะธะธ? +- ะะฐ ั‡ั‚ะพ ะพะฝ ั‚ะพั‡ะฝะพ ะฝะต ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ะฟะพั…ะพะถ? +- ะšะฐะบ ะดะพะปะถะตะฝ ะพั‰ัƒั‰ะฐั‚ัŒัั ะฟั€ะพะดัƒะบั‚: ัั‚ั€ะพะณะพ, ัƒั‚ะธะปะธั‚ะฐั€ะฝะพ, ะดั€ัƒะถะตะปัŽะฑะฝะพ, ะฟั€ะตะผะธะฐะปัŒะฝะพ, ะฑั‹ัั‚ั€ะพ, ัะบัะฟะตั€ั‚ะฝะพ? +- ะ•ัั‚ัŒ ะปะธ ั‡ั‚ะพ-ั‚ะพ, ั‡ั‚ะพ ั‚ั‹ ั‚ะพั‡ะฝะพ ะฝะต ั…ะพั‡ะตัˆัŒ ะฒะธะดะตั‚ัŒ: ั‚ะธะฟะพะฒะพะน ะปะตะฝะดะธะฝะณ, generic dashboard, ะปะธัˆะฝะธะน ะปะธั‡ะฝั‹ะน ะบะฐะฑะธะฝะตั‚, ะฟะตั€ะตะณั€ัƒะถะตะฝะฝั‹ะต ะฑะปะพะบะธ? +- ะะฐัะบะพะปัŒะบะพ ัะผะตะปั‹ะน ะดะธะทะฐะนะฝ ัƒะผะตัั‚ะตะฝ: ัะฟะพะบะพะนะฝั‹ะน, ะฒั‹ั€ะฐะทะธั‚ะตะปัŒะฝั‹ะน ะธะปะธ ะพั‡ะตะฝัŒ ัะผะตะปั‹ะน? +- ะัƒะถะฝั‹ ะปะธ ัะปะพะถะฝั‹ะต ั„ะพั€ะผั‹, ะฐัะธะผะผะตั‚ั€ะธั, ะฟะตั€ะตะบั€ั‹ั‚ะธั, ะฝะตะพะฑั‹ั‡ะฝั‹ะต ะฑะปะพะบะธ ะธะปะธ ะปัƒั‡ัˆะต ะฑะพะปะตะต ัั‚ั€ะพะณะธะน ะฒะธะทัƒะฐะปัŒะฝั‹ะน ัะทั‹ะบ? + +### ะ’ะพะปะฝะฐ 2. ะฃั‚ะพั‡ะฝะตะฝะธะต ะฟั€ะพะฑะตะปะพะฒ + +ะŸะพัะปะต ะพั‚ะฒะตั‚ะพะฒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั: + +- ะบะพั€ะพั‚ะบะพ ะฟะตั€ะตัะบะฐะถะธ, ั‡ั‚ะพ ั‚ั‹ ัƒะถะต ะฟะพะฝัะป +- ะพั‚ะดะตะปัŒะฝะพ ะฟะตั€ะตั‡ะธัะปะธ 3-5 ะฟั€ะพะฑะตะปะพะฒ ะธะปะธ ั€ะฐะทะฒะธะปะพะบ +- ะทะฐะดะฐะน ั‚ะพะปัŒะบะพ ัƒั‚ะพั‡ะฝััŽั‰ะธะต ะฒะพะฟั€ะพัั‹ ะฟะพ ัั‚ะธะผ ะฟั€ะพะฑะตะปะฐะผ +- ะบ ะบะฐะถะดะพะผัƒ ะฑะปะพะบัƒ ะฒะพะฟั€ะพัะพะฒ ะดะพะฑะฐะฒัŒ ะฟั€ะพัั‚ะพะต ะพะฑัŠััะฝะตะฝะธะต โ€œะทะฐั‡ะตะผ ั ัั‚ะพ ัƒั‚ะพั‡ะฝััŽโ€ + +ะ˜ัะฟะพะปัŒะทัƒะน ั‚ั€ะธ ะฑะปะพะบะฐ: + +#### ะ‘ะปะพะบ 4. ะ“ะปะฐะฒะฝั‹ะน ัั†ะตะฝะฐั€ะธะน + +- ะžะฟะธัˆะธ ะฟัƒั‚ัŒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั ะพั‚ ะฝะฐั‡ะฐะปะฐ ะดะพ ั€ะตะทัƒะปัŒั‚ะฐั‚ะฐ. +- ะ“ะดะต ะพะฝ ะทะฐั…ะพะดะธั‚? +- ะงั‚ะพ ะฝะฐะถะธะผะฐะตั‚? +- ะงั‚ะพ ะฒะธะดะธั‚ ะฒ ะบะพะฝั†ะต? +- ะงั‚ะพ ะฑัƒะดะตั‚ ัั‡ะธั‚ะฐั‚ัŒัั ัƒัะฟะตัˆะฝั‹ะผ ั€ะตะทัƒะปัŒั‚ะฐั‚ะพะผ? + +#### ะ‘ะปะพะบ 5. ะžะณั€ะฐะฝะธั‡ะตะฝะธั + +- ะญั‚ะพ ะดะพะปะถะตะฝ ะฑั‹ั‚ัŒ ะฟั€ะพัั‚ะพ MVP ะธะปะธ ัƒะถะต ะณะพั‚ะพะฒั‹ะน ั€ะฐะฑะพั‡ะธะน ะฟั€ะพะดัƒะบั‚? +- ะัƒะถะตะฝ ะทะฐะฟัƒัะบ ะฒ ะธะฝั‚ะตั€ะฝะตั‚ ัั€ะฐะทัƒ? +- ะ•ัั‚ัŒ ะปะธ ัะตั€ะฒะธัั‹, ะบะพั‚ะพั€ั‹ะต ัƒะถะต ั‚ะพั‡ะฝะพ ะฝะฐะดะพ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ? +- ะ•ัั‚ัŒ ะปะธ ั‡ั‚ะพ-ั‚ะพ, ั‡ั‚ะพ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฝะตะปัŒะทั? + +#### ะ‘ะปะพะบ 6. ะฃะฟั€ะพั‰ะตะฝะธะต + +- ะ•ัะปะธ ั…ะพั‡ะตั‚ัั ะทะฐะฟัƒัั‚ะธั‚ัŒ ะฑั‹ัั‚ั€ะตะต, ัะพะณะปะฐัะตะฝ ะปะธ ั‚ั‹ ะฟะพะบะฐ ัƒะฑั€ะฐั‚ัŒ ะปะธัˆะฝะตะต? +- ะงั‚ะพ ะธะท ัั‚ะพะณะพ ะผะพะถะฝะพ ะพั‚ะปะพะถะธั‚ัŒ ะฝะฐ ะฟะพั‚ะพะผ: auth, ะฑะฐะทะฐ, ะฐะดะผะธะฝะบะฐ, ะพะฟะปะฐั‚ั‹, ะ˜ะ˜? + +#### ะ‘ะปะพะบ 7. ะ”ะฐะฝะฝั‹ะต ะธ ะฑะตะทะพะฟะฐัะฝะพัั‚ัŒ + +ะ˜ัะฟะพะปัŒะทัƒะน ัั‚ะพั‚ ะฑะปะพะบ ั‚ะพะปัŒะบะพ ะตัะปะธ ะฟั€ะพะตะบั‚ ั€ะตะฐะปัŒะฝะพ ะทะฐั‚ั€ะฐะณะธะฒะฐะตั‚ ะดะฐะฝะฝั‹ะต, ะดะพัั‚ัƒะฟ, ะพะฟะปะฐั‚ั‹, ะฐะดะผะธะฝะบัƒ ะธะปะธ ะฒะฝะตัˆะฝะธะต ะธะฝั‚ะตะณั€ะฐั†ะธะธ. + +- ะšะฐะบะธะต ะดะฐะฝะฝั‹ะต ะทะดะตััŒ ะฒะพะพะฑั‰ะต ะฑัƒะดัƒั‚: ั‚ะพะปัŒะบะพ ะพั‚ะบั€ั‹ั‚ะฐั ะธะฝั„ะพั€ะผะฐั†ะธั ะธะปะธ ะดะฐะฝะฝั‹ะต ะฟะพะปัŒะทะพะฒะฐั‚ะตะปะตะน? +- ะัƒะถะฝะพ ะปะธ ะดะตะปะธั‚ัŒ ะฟั€ะฐะฒะฐ ะดะพัั‚ัƒะฟะฐ: ะพะฑั‹ั‡ะฝั‹ะน ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ, ะฐะดะผะธะฝ, ะพะฟะตั€ะฐั‚ะพั€? +- ะ•ัั‚ัŒ ะปะธ ะบะปัŽั‡ะธ, ั‚ะพะบะตะฝั‹, webhook secrets ะธะปะธ ัะตั€ะฒะธัะฝั‹ะต ะดะพัั‚ัƒะฟั‹, ะฑะตะท ะบะพั‚ะพั€ั‹ั… ะฟั€ะพะตะบั‚ ะฝะต ะทะฐั€ะฐะฑะพั‚ะฐะตั‚? +- ะ•ัั‚ัŒ ะปะธ ั‡ั‚ะพ-ั‚ะพ, ั‡ั‚ะพ ะฝะตะปัŒะทั ั…ั€ะฐะฝะธั‚ัŒ, ะปะพะณะธั€ะพะฒะฐั‚ัŒ ะธะปะธ ะฟะพะบะฐะทั‹ะฒะฐั‚ัŒ ะฒ ะบะปะธะตะฝั‚ะต? +- ะ•ัะปะธ ั…ะพั‡ะตั‚ัั ะฑั‹ัั‚ั€ะตะต ะทะฐะฟัƒัั‚ะธั‚ัŒัั, ะผะพะถะฝะพ ะปะธ ะฟะพะบะฐ ะพะฑะพะนั‚ะธััŒ ะฑะตะท ะปะธัˆะฝะธั… ะฟะตั€ัะพะฝะฐะปัŒะฝั‹ั… ะดะฐะฝะฝั‹ั…, ัะปะพะถะฝะพะน ะฐะฒั‚ะพั€ะธะทะฐั†ะธะธ ะธ ะฐะดะผะธะฝะบะธ? + +### ะŸั€ะฐะฒะธะปะพ ะพะฑัŠััะฝะตะฝะธั + +ะะพะฒะธั‡ะพะบ ะฝะต ะดะพะปะถะตะฝ ะณะฐะดะฐั‚ัŒ, ะฟะพั‡ะตะผัƒ ั‚ั‹ ัั‚ะพ ัะฟั€ะฐัˆะธะฒะฐะตัˆัŒ. + +ะ˜ัะฟะพะปัŒะทัƒะน ั„ะพั€ะผัƒะปะธั€ะพะฒะบะธ ะฒั€ะพะดะต: + +- โ€œะญั‚ะพ ะฝัƒะถะฝะพ, ั‡ั‚ะพะฑั‹ ะฝะต ั‚ะฐั‰ะธั‚ัŒ ะปะธัˆะฝะธะน backend ะฒ ะฟะตั€ะฒัƒัŽ ะฒะตั€ัะธัŽ.โ€ +- โ€œะญั‚ะพ ัƒั‚ะพั‡ะฝะตะฝะธะต ะฒะปะธัะตั‚ ะฝะฐ ั‚ะพ, ะฝัƒะถะตะฝ ะปะธ ั‚ะตะฑะต ะปะธั‡ะฝั‹ะน ะบะฐะฑะธะฝะตั‚.โ€ +- โ€œะญั‚ะพ ะฟะพะผะพะถะตั‚ ะฟะพะฝัั‚ัŒ, ะดะตะปะฐะตะผ ะปะธ ะผั‹ ะฟั€ะพัั‚ะพ ะปะตะฝะดะธะฝะณ ะธะปะธ ัƒะถะต ะฟะพะปะฝะพั†ะตะฝะฝั‹ะน ัะตั€ะฒะธั.โ€ +- โ€œะญั‚ะพ ะฒะฐะถะฝะพ, ั‡ั‚ะพะฑั‹ ะฟะพั‚ะพะผ ะฝะต ะฟะตั€ะตะดะตะปั‹ะฒะฐั‚ัŒ ะฝะฐะฒะธะณะฐั†ะธัŽ ัƒ ะฑะพั‚ะฐ.โ€ +- โ€œะ•ัะปะธ ั…ะพั‡ะตัˆัŒ ะทะฐะฟัƒัั‚ะธั‚ัŒัั ะฑั‹ัั‚ั€ะตะต, ั ะฑั‹ ะฟะพะบะฐ ัƒะฑั€ะฐะป ะฐะฒั‚ะพั€ะธะทะฐั†ะธัŽ. ะžัั‚ะฐะฒะปัะตะผ ะฑะตะท ะฝะตั‘?โ€ + +### ะคะพั€ะผะฐั‚ ะบะฐะถะดะพะณะพ ะฒะพะฟั€ะพัะฐ + +ะšะพะณะดะฐ ะฒะพะฟั€ะพั ะฒะปะธัะตั‚ ะฝะฐ ัั‚ะตะบ ะธะปะธ scope, ะพั„ะพั€ะผะปัะน ะตะณะพ ั‚ะฐะบ: + +- ะ’ะพะฟั€ะพั +- ะ—ะฐั‡ะตะผ ัะฟั€ะฐัˆะธะฒะฐัŽ +- ะœะพั ั€ะตะบะพะผะตะฝะดะฐั†ะธั, ะตัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฝะต ัƒะฒะตั€ะตะฝ +- ะงั‚ะพ ัั‚ะพ ะผะตะฝัะตั‚ ะฒ ะฟะตั€ะฒะพะน ะฒะตั€ัะธะธ + +ะŸั€ะธะผะตั€: + +- ะ’ะพะฟั€ะพั: โ€œะัƒะถะฝะพ ะปะธ ั‡ั‚ะพ-ั‚ะพ ัะพั…ั€ะฐะฝัั‚ัŒ ะผะตะถะดัƒ ะทะฐั…ะพะดะฐะผะธ?โ€ +- ะ—ะฐั‡ะตะผ ัะฟั€ะฐัˆะธะฒะฐัŽ: โ€œะญั‚ะพ ะฒะปะธัะตั‚ ะฝะฐ ั‚ะพ, ะฝัƒะถะฝะฐ ะปะธ ะฑะฐะทะฐ ะดะฐะฝะฝั‹ั….โ€ +- ะœะพั ั€ะตะบะพะผะตะฝะดะฐั†ะธั: โ€œะ•ัะปะธ ัะตะนั‡ะฐั ะฒะฐะถะฝะพ ะฟั€ะพะฒะตั€ะธั‚ัŒ ะธะดะตัŽ, ะปัƒั‡ัˆะต ัะฝะฐั‡ะฐะปะฐ ะฑะตะท ะฑะฐะทั‹.โ€ +- ะงั‚ะพ ัั‚ะพ ะผะตะฝัะตั‚ ะฒ ะฟะตั€ะฒะพะน ะฒะตั€ัะธะธ: โ€œะขะพะณะดะฐ ะผั‹ ะผะพะถะตะผ ะฝะต ั‚ะฐั‰ะธั‚ัŒ backend ะฝะฐ ัั‚ะฐั€ั‚ะต ะธ ะฑั‹ัั‚ั€ะตะต ัะพะฑั€ะฐั‚ัŒ MVP.โ€ + +### ะŸั€ะฐะฒะธะปะพ ะดะพัั‚ะฐั‚ะพั‡ะฝะพัั‚ะธ + +ะะต ะฟะตั€ะตั…ะพะดะธ ะบ ะฟะปะฐะฝัƒ, ะฟะพะบะฐ ะฝะต ะทะฐั„ะธะบัะธั€ะพะฒะฐะฝั‹: + +- ะณะปะฐะฒะฝั‹ะน ัั†ะตะฝะฐั€ะธะน v1 +- ะบั‚ะพ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ +- ั‡ั‚ะพ ั‚ะพั‡ะฝะพ ะฝะต ะฒั…ะพะดะธั‚ ะฒ v1 +- ั‡ั‚ะพ ะพะฑัะทะฐั‚ะตะปัŒะฝะพ ะฒั…ะพะดะธั‚ ะฒ v1 +- ั‡ั‚ะพ ะดะตะปะฐะตั‚ ัั‚ะพั‚ ะฟั€ะพะตะบั‚ ะฝะต-ัˆะฐะฑะปะพะฝะฝั‹ะผ +- ะบะฐะบะธะต ั€ะตัˆะตะฝะธั ะทะดะตััŒ ะฑัƒะดัƒั‚ ั‡ัƒะถะธะผะธ ะธะปะธ ะปะธัˆะฝะธะผะธ +- ะบะฐะบะธะต security-ั€ะตัˆะตะฝะธั ั€ะตะฐะปัŒะฝะพ ะพะฑัะทะฐั‚ะตะปัŒะฝั‹, ะฐ ะบะฐะบะธะต ะฟะพะบะฐ ะผะพะถะฝะพ ะฝะต ั‚ะฐั‰ะธั‚ัŒ +- ะบะฐะบะธะต ั‚ะตั…ะฝะธั‡ะตัะบะธะต ะฒะตั‰ะธ ั€ะตะฐะปัŒะฝะพ ะฒะปะธััŽั‚ ะฝะฐ ัั‚ะตะบ +- ะบะฐะบะธะต ัะฟะพั€ะฝั‹ะต ั‡ะฐัั‚ะธ ั‚ั€ะตะฑัƒัŽั‚ ะพั‚ะดะตะปัŒะฝะพะณะพ ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะธั +- ะบะฐะบะพะน ะฒะฐั€ะธะฐะฝั‚ ะฟะปะฐะฝะฐ ะฒะตั€ะพัั‚ะฝะตะต ะฒัะตะณะพ ั€ะตะบะพะผะตะฝะดะพะฒะฐั‚ัŒ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ั ะฟะพะฝัะป, ั‡ั‚ะพ ัั‚ะพ ะทะฐ ะฟั€ะพะดัƒะบั‚? +- ั ะฟะพะฝัะป, ะดะปั ะบะพะณะพ ะพะฝ? +- ั ะฟะพะฝัะป, ะบะฐะบะพะน ะณะปะฐะฒะฝั‹ะน ัั†ะตะฝะฐั€ะธะน ะดะพะปะถะตะฝ ะทะฐั€ะฐะฑะพั‚ะฐั‚ัŒ ะฟะตั€ะฒั‹ะผ? +- ั ะฟะพะฝัะป, ั‡ั‚ะพ ะฝะต ะฒั…ะพะดะธั‚ ะฒ v1? +- ั ะทะฐะดะฐะป ะฒั‚ะพั€ัƒัŽ ะฒะพะปะฝัƒ ัƒั‚ะพั‡ะฝะตะฝะธะน, ะตัะปะธ ะฟะพัะปะต ะฟะตั€ะฒะพะน ะบะฐั€ั‚ะธะฝั‹ ะฑั‹ะปะธ ะฒะฐะถะฝั‹ะต ะฟั€ะพะฑะตะปั‹? +- ั ะพะฑัŠััะฝะธะป ั‡ะตะปะพะฒะตะบัƒ, ะทะฐั‡ะตะผ ะฝัƒะถะฝั‹ ะผะพะธ ัƒั‚ะพั‡ะฝััŽั‰ะธะต ะฒะพะฟั€ะพัั‹? +- ั ัะผะพะณัƒ ะฟะพั‚ะพะผ ะฟั€ะตะดะปะพะถะธั‚ัŒ 3 ะฟะพะฝัั‚ะฝั‹ั… ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ ะฑะตะท ะปะธัˆะฝะตะณะพ? + +## Handoff ะฐั€ั…ะธั‚ะตะบั‚ะพั€ัƒ + +ะŸะตั€ะตะดะฐะน ะดะฐะปัŒัˆะต: + +- ะณะปะฐะฒะฝั‹ะน ัั†ะตะฝะฐั€ะธะน +- ั‡ั‚ะพ ัะฒะฝะพ ะฝะต ะฒั…ะพะดะธั‚ ะฒ v1 +- ะบะฐะบะธะต ะพั‚ะฒะตั‚ั‹ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ะฝะต ะทะฝะฐะตั‚ +- ะบะฐะบะธะต ะฟั€ะตะดะฟะพะปะพะถะตะฝะธั ัƒะถะต ะฟั€ะธัˆะปะพััŒ ัะดะตะปะฐั‚ัŒ +- ะบะฐะบะธะต ัƒั‚ะพั‡ะฝะตะฝะธั ะตั‰ั‘ ะผะพะณัƒั‚ ะฟะพะฒะปะธัั‚ัŒ ะฝะฐ ะฒั‹ะฑะพั€ ะผะตะถะดัƒ `ะผะธะฝะธะผัƒะผ`, `ะพะฟั‚ะธะผะฐะปัŒะฝะพ` ะธ `ั ะทะฐะฟะฐัะพะผ` diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/qa-reviewer/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/qa-reviewer/SKILL.md new file mode 100644 index 0000000..975198d --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/qa-reviewer/SKILL.md @@ -0,0 +1,68 @@ +--- +name: qa-reviewer +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะดะปั verification/handoff; ะฝะต ะฒะบะปัŽั‡ะฐะน ะดะปั ะพะฑั‹ั‡ะฝะพะณะพ code review ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# QA-ะฐะฝะฐะปะธั‚ะธะบ + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฒะบะปัŽั‡ะฐะน ัั‚ะพั‚ skill ะฐะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะธ ะดะปั ะปัŽะฑะพะณะพ ั€ะตะฒัŒัŽ-ะบะตะนัะฐ. ะ’ะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ ะดะตะนัั‚ะฒัƒะตั‚ ะพะฑั‹ั‡ะฝั‹ะน review-ะฟะพะดั…ะพะด Codex. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ะฟั€ะฐะฒะดัƒ ะฟะตั€ะตะด ั„ะธะฝะฐะปะพะผ. + +## ะ’ั…ะพะด + +- `implementation-plan.md` +- `execution-log.md` +- `verification-report.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- findings +- `verification-report.md` +- `scorecard.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ัะฝะฐั‡ะฐะปะฐ ะฟะธัะฐั‚ัŒ findings +- ะฟั€ะพะฒะตั€ัั‚ัŒ happy path +- ะฟั€ะพะฒะตั€ัั‚ัŒ ั…ะพั‚ั ะฑั‹ ะพะดะธะฝ ะฟะปะพั…ะพะน ัั†ะตะฝะฐั€ะธะน +- ะพั‚ะผะตั‡ะฐั‚ัŒ, ั‡ั‚ะพ ะฝะต ะฟั€ะพะฒะตั€ะตะฝะพ +- ะฒั‹ัั‚ะฐะฒะปัั‚ัŒ scorecard ะฟั€ะพะตะบั‚ะฐ +- ะพั‚ะดะตะปัŒะฝะพ ะฟั€ะพะฒะตั€ัั‚ัŒ desktop, tablet ะธ mobile +- ะฟั€ะพะฒะตั€ัั‚ัŒ ะฐะดะฐะฟั‚ะธะฒ ะฝะต ั‚ะพะปัŒะบะพ ะฝะฐ โ€œั€ะฐะฑะพั‚ะฐะตั‚ / ะฝะต ั€ะฐะฑะพั‚ะฐะตั‚โ€, ะฐ ะฝะฐ ั‡ะธั‚ะฐะตะผะพัั‚ัŒ, ะฟะปะพั‚ะฝะพัั‚ัŒ ะธ ะพั‚ััƒั‚ัั‚ะฒะธะต ะฒะธะทัƒะฐะปัŒะฝั‹ั… ะฟะพะปะพะผะพะบ +- ั„ะธะบัะธั€ะพะฒะฐั‚ัŒ ะบะพะฝะบั€ะตั‚ะฝั‹ะต viewport size, ะฝะฐ ะบะพั‚ะพั€ั‹ั… ะฟั€ะพะฒะพะดะธะปะฐััŒ ะฟั€ะพะฒะตั€ะบะฐ +- ะตัะปะธ ะฟั€ะพะตะบั‚ ะบะฐัะฐะตั‚ัั ะดะฐะฝะฝั‹ั…, auth, ะฟะปะฐั‚ะตะถะตะน ะธะปะธ ะธะฝั‚ะตะณั€ะฐั†ะธะน, ะพั‚ะดะตะปัŒะฝะพ ะฟั€ะพะฒะตั€ัั‚ัŒ ัะตะบั€ะตั‚ั‹, ะดะพัั‚ัƒะฟ ะธ ะฟัƒั‚ัŒ ะฟั€ะพะฒะตั€ะบะธ ะทะฐะฒะธัะธะผะพัั‚ะตะน + +## QA-ะฟะพะดั…ะพะด Morecil + +ะขั‹ ะฝัƒะถะตะฝ ะฝะต ะดะปั ั„ะพั€ะผะฐะปัŒะฝะพะน ะณะฐะปะพั‡ะบะธ, ะฐ ั‡ั‚ะพะฑั‹ ะพัั‚ะฐะฝะพะฒะธั‚ัŒ ัะฐะผะพะพะฑะผะฐะฝ ะบะพะผะฐะฝะดั‹. + +ะ•ัะปะธ ั‡ั‚ะพ-ั‚ะพ ะฝะต ะฟั€ะพะฒะตั€ะตะฝะพ, ัั‚ะพ ะดะพะปะถะฝะพ ะฑั‹ั‚ัŒ ะฝะฐะฟะธัะฐะฝะพ ัะฒะฝะพ. + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะฟะธัะฐั‚ัŒ โ€œะฒัั‘ ะพะบโ€, ะตัะปะธ ะฝะธั‡ะตะณะพ ั‚ะพะปะบะพะผ ะฝะต ะฟั€ะพะฒะตั€ะตะฝะพ +- ะฟั€ะพะฟัƒัะบะฐั‚ัŒ ะฟั€ะพะฑะปะตะผั‹ ะฑะตะทะพะฟะฐัะฝะพัั‚ะธ, handoff ะธะปะธ UX +- ะพะดะพะฑั€ัั‚ัŒ ั„ะธะฝะฐะป ะฟั€ะธ ัˆะฐะฑะปะพะฝะฝั‹ั… ะฐั€ั‚ะตั„ะฐะบั‚ะฐั… +- ะพะดะพะฑั€ัั‚ัŒ UI, ะตัะปะธ ะฝะฐ mobile ะตัั‚ัŒ ะฒั‹ะปะตะทะฐะฝะธะต ั‚ะตะบัั‚ะฐ, ั‚ะตัะฝั‹ะต ะฑะปะพะบะธ, ัะปัƒั‡ะฐะนะฝั‹ะต ะฟะตั€ะตะฝะพัั‹ ะธะปะธ ะฝะตัƒะดะพะฑะฝั‹ะต ะบะฝะพะฟะบะธ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะตัั‚ัŒ ะปะธ ั€ะตะฐะปัŒะฝั‹ะต findings ะธะปะธ ะธั… ะฟั€ะฐะฒะดะฐ ะฝะตั‚? +- ั…ะฒะฐั‚ะธั‚ ะปะธ handoff ะฝะพะฒะพะผัƒ ั‡ะตะปะพะฒะตะบัƒ? +- scorecard ั‡ะตัั‚ะฝั‹ะน? +- ะฟั€ะพะฒะตั€ะตะฝั‹ ะปะธ ั…ะพั‚ั ะฑั‹ `1440`, `768` ะธ `375`? +- ะทะฐั„ะธะบัะธั€ะพะฒะฐะฝั‹ ะปะธ ั€ะตะฐะปัŒะฝั‹ะต UX-ะฟะพะปะพะผะบะธ mobile, ะตัะปะธ ะพะฝะธ ะตัั‚ัŒ? +- ะพั‚ะผะตั‡ะตะฝะพ ะปะธ, ั‡ะตะผ ะฟั€ะพะฒะตั€ัะปะฐััŒ ะฑะตะทะพะฟะฐัะฝะพัั‚ัŒ ะธ ะทะฐะฒะธัะธะผะพัั‚ะธ? + +## Handoff ะดะตะฟะปะพัŽ ะธ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ัƒ + +ะŸะตั€ะตะดะฐะน: + +- ั‡ั‚ะพ ั€ะตะฐะปัŒะฝะพ ะฟะพะดั‚ะฒะตั€ะถะดะตะฝะพ +- ั‡ั‚ะพ ะพัั‚ะฐั‘ั‚ัั ั€ะธัะบะพะผ +- ะบะฐะบะธะต ั€ัƒั‡ะฝั‹ะต ะฟั€ะพะฒะตั€ะบะธ ะดะพะปะถะตะฝ ะฟะพะฒั‚ะพั€ะธั‚ัŒ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ diff --git a/plugins/AlexMi64/codex-project-autopilot/skills/solution-architect/SKILL.md b/plugins/AlexMi64/codex-project-autopilot/skills/solution-architect/SKILL.md new file mode 100644 index 0000000..d8fdb14 --- /dev/null +++ b/plugins/AlexMi64/codex-project-autopilot/skills/solution-architect/SKILL.md @@ -0,0 +1,80 @@ +--- +name: solution-architect +description: ะ˜ัะฟะพะปัŒะทัƒะน ั‚ะพะปัŒะบะพ ะฒะฝัƒั‚ั€ะธ ะฐะบั‚ะธะฒะฝะพะณะพ Codex Project Autopilot-ะฟั€ะพะตะบั‚ะฐ ะฟะพัะปะต discovery ะธะปะธ approval, ะฐ ะฝะต ะดะปั ะพะฑั‹ั‡ะฝั‹ั… ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฝั‹ั… ะฒะพะฟั€ะพัะพะฒ ะฒะฝะต ะฐะฒั‚ะพะฟะธะปะพั‚ะฐ. +--- + +# ะั€ั…ะธั‚ะตะบั‚ะพั€ ั€ะตัˆะตะฝะธั + +## ะŸั€ะฐะฒะธะปะพ ะฐะบั‚ะธะฒะฐั†ะธะธ + +ะะต ะฒะบะปัŽั‡ะฐะน ัั‚ะพั‚ skill ะฟั€ะพัั‚ะพ ะธะท-ะทะฐ ัะปะพะฒ `ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ`, `ัั‚ะตะบ` ะธะปะธ `ะฟะปะฐะฝ`, ะตัะปะธ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปัŒ ัะฒะฝะพ ะฝะต ั€ะฐะฑะพั‚ะฐะตั‚ ั‡ะตั€ะตะท ะฐะฒั‚ะพะฟะธะปะพั‚. + +ะ•ัะปะธ ะฒ ั‚ะตะบัƒั‰ะตะผ workspace ะฝะตั‚ `.codex-agent/state.json`, ัั‚ะพั‚ skill ะฝะต ะธะผะตะตั‚ ะฟั€ะฐะฒะฐ ะฝะฐั‡ะธะฝะฐั‚ัŒ ั€ะฐะฑะพั‚ัƒ ะธ ะดะพะปะถะตะฝ ะฒะตั€ะฝัƒั‚ัŒ ะทะฐะดะฐั‡ัƒ ะพั€ะบะตัั‚ั€ะฐั‚ะพั€ัƒ ะฝะฐ bootstrap. + +ะขั‹ ะพั‚ะฒะตั‡ะฐะตัˆัŒ ะทะฐ ั€ะตัˆะตะฝะธะต, ะฐ ะฝะต ะทะฐ ะบั€ะฐัะพั‚ัƒ ั„ะพั€ะผัƒะปะธั€ะพะฒะพะบ. + +## ะ’ั…ะพะด + +- `project-brief.md` +- `product-intelligence.md` +- `product-context.md` +- `tech-context.md` +- `state.json` + +## ะ’ั‹ั…ะพะด + +- `implementation-plan.md` +- `plan-variants.md` +- `beginner-guide.md` +- `active-context.md` +- `progress.md` +- ะพะฑะฝะพะฒะปะตะฝะฝั‹ะน `state.json` + +## ะžะฑัะทะฐะฝ + +- ะฒั‹ะฑั€ะฐั‚ัŒ ัั‚ะตะบ ะฟะพะด ะทะฐะดะฐั‡ัƒ, ะฐ ะฝะต ะฟะพ ะผะพะดะต +- ะดะตั€ะถะฐั‚ัŒ scope ะผะฐะปะตะฝัŒะบะธะผ +- ะพะณั€ะฐะฝะธั‡ะธะฒะฐั‚ัŒ ะฟะตั€ะฒัƒัŽ ะฒะตั€ัะธัŽ 3-5 ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ะผะธ deliverables +- ัะฒะฝะพ ั€ะฐะทะดะตะปัั‚ัŒ frontend, backend, database, automation +- ะฒั‹ะฑั€ะฐั‚ัŒ playbook +- ะทะฐั„ะธะบัะธั€ะพะฒะฐั‚ัŒ acceptance criteria +- ะทะฐะฟะธัะฐั‚ัŒ ะธะทะฒะตัั‚ะฝั‹ะต ั€ะธัะบะธ +- ะฒั‹ะฑั€ะฐั‚ัŒ ะฑะตะทะพะฟะฐัะฝั‹ะต ะดะตั„ะพะปั‚ั‹: secrets ั‡ะตั€ะตะท env, ะผะธะฝะธะผะธะทะฐั†ะธั ะดะฐะฝะฝั‹ั…, ัะฒะฝั‹ะต ะณั€ะฐะฝะธั†ั‹ ะดะพัั‚ัƒะฟะฐ +- ะพะฟะธัะฐั‚ัŒ, ั‡ั‚ะพ ะฝัƒะถะฝะพ ะพั‚ ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั ะฒั€ัƒั‡ะฝัƒัŽ +- ะฒั‹ะฝะตัั‚ะธ ัะพะฒะตั‚ั‹ ะธ ัƒัะธะปะตะฝะธั ะฒ ะพั‚ะดะตะปัŒะฝั‹ะน ะฑะปะพะบ, ะฝะต ัะผะตัˆะธะฒะฐั ะธั… ั MVP +- ะพั„ะพั€ะผะธั‚ัŒ ั‚ั€ะธ ะฒะฐั€ะธะฐะฝั‚ะฐ ะฟะปะฐะฝะฐ: ะผะธะฝะธะผัƒะผ, ะพะฟั‚ะธะผะฐะปัŒะฝะพ, ั ะทะฐะฟะฐัะพะผ +- ั€ะตะบะพะผะตะฝะดะพะฒะฐั‚ัŒ ะพะดะธะฝ ะฒะฐั€ะธะฐะฝั‚ ะธ ะพะฑัŠััะฝะธั‚ัŒ ัั‚ะพ ะฟั€ะพัั‚ั‹ะผะธ ัะปะพะฒะฐะผะธ + +## ะั€ั…ะธั‚ะตะบั‚ัƒั€ะฝั‹ะน ั…ะฐั€ะฐะบั‚ะตั€ + +ะขั‹ ะฝะต ั€ะธััƒะตัˆัŒ โ€œะบั€ะฐัะธะฒัƒัŽ ัะธัั‚ะตะผัƒโ€. +ะขั‹ ั€ะตะถะตัˆัŒ ะปะธัˆะฝะตะต, ั‡ั‚ะพะฑั‹ ะฟั€ะพะตะบั‚: + +- ะผะพะถะฝะพ ะฑั‹ะปะพ ั€ะตะฐะปัŒะฝะพ ะดะพะฒะตัั‚ะธ ะดะพ ะบะพะฝั†ะฐ +- ะผะพะถะฝะพ ะฑั‹ะปะพ ะฟั€ะพะฒะตั€ะธั‚ัŒ +- ะผะพะถะฝะพ ะฑั‹ะปะพ ะพะฑัŠััะฝะธั‚ัŒ ะฝะพะฒะธั‡ะบัƒ +- ะผะพะถะฝะพ ะฑั‹ะปะพ ะฟั€ะพะดะพะปะถะธั‚ัŒ ะฑะตะท ะฟะตั€ะตัะฑะพั€ะบะธ ั ะฝัƒะปั + +## ะ—ะฐะฟั€ะตั‰ะตะฝะพ + +- ะณะพั€ะพะดะธั‚ัŒ โ€œะผะธะฝะธ-enterpriseโ€ ะธะท MVP +- ะดะพะฑะฐะฒะปัั‚ัŒ auth, billing, AI, ะฑะฐะทัƒ ะธ ะฐะดะผะธะฝะบัƒ ะฑะตะท ะฟั€ะธั‡ะธะฝั‹ +- ะดะพะฑะฐะฒะปัั‚ัŒ ั…ั€ะฐะฝะตะฝะธะต ั‡ัƒะฒัั‚ะฒะธั‚ะตะปัŒะฝั‹ั… ะดะฐะฝะฝั‹ั… ะฑะตะท ะฟะพะฝัั‚ะฝะพะน ะฟั€ะธั‡ะธะฝั‹ ะธ ะผะพะดะตะปะธ ะดะพัั‚ัƒะฟะฐ +- ะฟั€ะตะฒั€ะฐั‰ะฐั‚ัŒ ั€ะตะบะพะผะตะฝะดะฐั†ะธะธ ะฒ ะพะฑัะทะฐั‚ะตะปัŒะฝั‹ะต ะทะฐะดะฐั‡ะธ ะฑะตะท ั€ะตัˆะตะฝะธั ะฟะพะปัŒะทะพะฒะฐั‚ะตะปั +- ะผะฐัะบะธั€ะพะฒะฐั‚ัŒ ะฐั€ั…ะธั‚ะตะบั‚ัƒั€ะฝัƒัŽ ะฝะตะพะฟั€ะตะดะตะปะตะฝะฝะพัั‚ัŒ ะบั€ะฐัะธะฒั‹ะผะธ ัะปะพะฒะฐะผะธ + +## ะกะฐะผะพะฟั€ะพะฒะตั€ะบะฐ + +- ะผะพะถะฝะพ ะปะธ ั€ะตะฐะปะธะทะพะฒะฐั‚ัŒ ัั‚ะพั‚ ะฟะปะฐะฝ ะฑะตะท ะปะธัˆะฝะธั… ั€ะตัˆะตะฝะธะน ะฟะพ ั…ะพะดัƒ? +- ะฝะตั‚ ะปะธ ะทะดะตััŒ ะฟะตั€ะตัƒัะปะพะถะฝะตะฝะธั? +- ะฝะต ะฝะฐั€ัƒัˆะตะฝ ะปะธ anti-big-bang ะฟั€ะธะฝั†ะธะฟ? +- ะฟะพะฝัั‚ะฝะฐ ะปะธ ะฝะพะฒะธั‡ะบัƒ ั€ะฐะทะฝะธั†ะฐ ะผะตะถะดัƒ ั‚ั€ะตะผั ะฒะฐั€ะธะฐะฝั‚ะฐะผะธ ะฟะปะฐะฝะฐ? + +## Handoff ัะปะตะดัƒัŽั‰ะธะผ ั€ะพะปัะผ + +ะŸะตั€ะตะดะฐะฒะฐะน ะดะฐะปัŒัˆะต ั‚ะพะปัŒะบะพ: + +- ัƒั‚ะฒะตั€ะถะดั‘ะฝะฝั‹ะน MVP +- ั€ะตะฐะปัŒะฝั‹ะต deliverables +- ั„ะฐะนะปั‹-ะธัั‚ะพั‡ะฝะธะบะธ ะธัั‚ะธะฝั‹ +- ัะฟะธัะพะบ ัะฟะพั€ะฝั‹ั… ะผะตัั‚, ะตัะปะธ ะพะฝะธ ะพัั‚ะฐะปะธััŒ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/.codex-plugin/plugin.json b/plugins/BlockchainHB/launchfast_codex_plugin/.codex-plugin/plugin.json new file mode 100644 index 0000000..e22a970 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/.codex-plugin/plugin.json @@ -0,0 +1,50 @@ +{ + "name": "launchfast", + "version": "0.1.1", + "description": "LaunchFast Amazon seller research plugin for Codex with bundled FBA workflows and the LaunchFast MCP server.", + "author": { + "name": "Launch Fast", + "url": "https://launchfastlegacyx.com" + }, + "homepage": "https://launchfastlegacyx.com", + "repository": "https://github.com/BlockchainHB/launchfast_codex_plugin", + "license": "MIT", + "keywords": [ + "amazon-fba", + "product-research", + "keyword-research", + "supplier-sourcing", + "ppc", + "trademark", + "patent" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "LaunchFast", + "shortDescription": "Amazon seller research tools for Codex", + "longDescription": "Connect Codex to the production LaunchFast MCP server and bundle reusable Amazon FBA workflows for product research, PPC planning, supplier sourcing, and IP risk checks. Authentication uses Codex's MCP OAuth flow against LaunchFast, including expected localhost or 127.0.0.1 loopback callbacks during authorization.", + "developerName": "Launch Fast", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://launchfastlegacyx.com", + "privacyPolicyURL": "https://launchfastlegacyx.com/privacy", + "termsOfServiceURL": "https://launchfastlegacyx.com/terms", + "defaultPrompt": [ + "Research this Amazon keyword with LaunchFast", + "Run a full FBA opportunity report for this niche", + "Find supplier and PPC angles for this product" + ], + "brandColor": "#111111", + "composerIcon": "./assets/icon.png", + "logo": "./assets/logo.png", + "screenshots": [ + "./assets/screenshot1.png", + "./assets/screenshot2.png", + "./assets/screenshot3.png" + ] + } +} diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/assets/icon.png b/plugins/BlockchainHB/launchfast_codex_plugin/assets/icon.png new file mode 100644 index 0000000..ab28709 Binary files /dev/null and b/plugins/BlockchainHB/launchfast_codex_plugin/assets/icon.png differ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/assets/logo.png b/plugins/BlockchainHB/launchfast_codex_plugin/assets/logo.png new file mode 100644 index 0000000..ab28709 Binary files /dev/null and b/plugins/BlockchainHB/launchfast_codex_plugin/assets/logo.png differ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot1.png b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot1.png new file mode 100644 index 0000000..09cf98d Binary files /dev/null and b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot1.png differ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot2.png b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot2.png new file mode 100644 index 0000000..ae08997 Binary files /dev/null and b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot2.png differ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot3.png b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot3.png new file mode 100644 index 0000000..ae08997 Binary files /dev/null and b/plugins/BlockchainHB/launchfast_codex_plugin/assets/screenshot3.png differ diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/alibaba-supplier-outreach/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/alibaba-supplier-outreach/SKILL.md new file mode 100644 index 0000000..2ee1434 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/alibaba-supplier-outreach/SKILL.md @@ -0,0 +1,132 @@ +--- +name: alibaba-supplier-outreach +description: | + Codex-native supplier sourcing and outreach workflow for Alibaba using + LaunchFast research. Use when the user wants supplier shortlists, outreach + messages, reply triage, or negotiation support. + + Requires `supplier_research`. Browser automation is optional but useful when + the user wants Codex to interact with Alibaba directly. + +argument-hint: "[product keyword] | check replies | follow up [supplier]" +--- + +# Alibaba Supplier Outreach + +This skill has three modes: outreach, reply review, and follow-up drafting. + +## Mode detection + +- Product keyword or โ€œfind suppliersโ€ -> OUTREACH +- โ€œcheck repliesโ€, โ€œany responsesโ€ -> REPLY REVIEW +- โ€œfollow upโ€, โ€œreply to supplierโ€ -> FOLLOW-UP + +## Shared defaults + +Use these defaults when the user does not care: + +- first order quantity: 500 units +- shortlist size: top 5 suppliers +- conversation notes path: `./artifacts/launchfast/supplier-conversations/` + +## OUTREACH + +### 1. Gather context + +Ask once for: + +- product keyword +- target price or landed-cost goal +- target first order quantity +- sign-off name or company +- optional Amazon selling experience + +### 2. Research suppliers + +Run: + +```text +supplier_research(keyword="", goldSupplierOnly=true, tradeAssuranceOnly=true, maxResults=10) +``` + +Present a compact shortlist with: + +- supplier name +- quality score +- price +- MOQ +- years in business +- trust signals + +### 3. Draft the outreach + +Use this structure: + +1. Mention the supplier by name and one concrete credibility signal. +2. Establish buyer credibility briefly. +3. State quantity and target pricing clearly. +4. Ask exactly 3 questions: + - best price at target quantity + - lead time + - private-label capability +5. End with a warm but direct close. + +Always show the message to the user before sending it anywhere. + +### 4. Browser automation, if requested + +If the user wants Codex to send messages and browser automation tools are available, use this concrete flow: + +1. Open Alibaba in the browser automation session. +2. Confirm the user is already logged in before proceeding. +3. Navigate to the supplier page or Alibaba messaging UI. +4. Use page inspection or accessibility snapshot tooling to find the `Contact Supplier` or reply form. +5. Click into the message textarea and paste the approved message verbatim. +6. Submit the form. +7. Confirm success by checking for a sent-state confirmation or the new message appearing in the thread. +8. Save the conversation summary to the local notes path. + +If browser automation is unavailable, stop after drafting the approved message set. + +### 5. Save notes + +Store outreach notes under: + +`./artifacts/launchfast/supplier-conversations/[supplier-slug]/conversation.md` + +Keep a simple index file at: + +`./artifacts/launchfast/supplier-conversations/index.md` + +## REPLY REVIEW + +When the user asks to check replies: + +- use browser automation if available and authenticated +- open Alibaba messages +- inspect the conversation list for unread or recent threads +- open each relevant thread +- extract pricing, MOQ, lead time, sample terms, and direct supplier questions +- summarize supplier-by-supplier +- update the conversation note files + +If browser automation is unavailable, ask the user to provide exported text or screenshots and continue from that material. + +## FOLLOW-UP + +When drafting or sending a reply: + +- read the relevant conversation note file first if it exists +- preserve negotiation context +- answer supplier questions directly +- push toward quote clarity, samples, lead time, packaging, and payment terms +- ask for approval before sending any reply through the browser + +If browser automation is used for the send: + +1. Open the supplier thread. +2. Locate the reply textarea. +3. Paste the approved response. +4. Submit. +5. Verify the message appears in the thread. +6. Update the local notes file with the sent reply and timestamp. diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/batch-product-research/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/batch-product-research/SKILL.md new file mode 100644 index 0000000..ec7b4ef --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/batch-product-research/SKILL.md @@ -0,0 +1,90 @@ +--- +name: batch-product-research +description: | + Codex-native batch Amazon keyword research using LaunchFast MCP. Use when the + user wants a ranked comparison across many keywords and optionally wants HTML + and CSV artifacts written to disk. +--- + +# Batch Product Research + +Use this skill for 1-20 keywords. + +## Inputs + +Accept: + +- comma-separated keywords +- numbered lists +- a local file path containing keywords + +Defaults: + +- maximum 20 keywords per run +- report path: `./artifacts/launchfast/batch-research/report-[YYYY-MM-DD].html` +- csv path: `./artifacts/launchfast/batch-research/report-[YYYY-MM-DD].csv` + +## Workflow + +### 1. Normalize input + +- trim whitespace +- deduplicate case-insensitively +- if there are more than 20 keywords, split into chunks of 20 and process chunk-by-chunk + +### 2. Run balanced product research + +- run `research_products` for every keyword +- prefer parallel tool calls where practical +- do not require delegation + +### 3. Score each keyword + +For each keyword compute: + +- search volume +- total niche revenue +- average price +- average reviews +- average revenue per seller +- top-seller dominance +- estimated margin using conservative assumptions +- opportunity score and verdict + +Use verdicts: + +- VIABLE +- MARGINAL +- NOT RECOMMENDED +- ERROR + +### 4. Optional deeper passes + +For VIABLE or MARGINAL keywords only: + +- run `research_products(... focus="financial")` +- optionally run `amazon_keyword_research` on the top 2-3 ASINs if keyword depth matters for the userโ€™s goal + +### 5. Present ranked results + +Always include a comparison table first. + +Then provide concise cards or sections for the strongest keywords. + +### 6. Write artifacts when useful + +If the user asked for files, or a file materially improves the result: + +- write an HTML report +- write a CSV export + +Keep the file generation deterministic. Prefer Python for CSV writing. + +## Output + +At minimum return: + +- number of keywords processed +- ranking table +- top recommendations +- artifact paths when files were written diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/kunze-ad-setup/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/kunze-ad-setup/SKILL.md new file mode 100644 index 0000000..d2f5efb --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/kunze-ad-setup/SKILL.md @@ -0,0 +1,124 @@ +--- +name: kunze-ad-setup +description: | + Codex-native Amazon PPC setup workflow using Kunze's broader ecosystem-driven + strategy. Use when the user wants LaunchFast-driven bulk-sheet generation with + broad and phrase coverage, gap analysis, and a campaign package written to disk. +--- + +# Kunze Ad Setup + +## Inputs + +Ask once for: + +- main keyword +- product SKU +- optional product name +- optional budget level: conservative or aggressive +- optional output path + +Defaults: + +- budget level: conservative +- output directory: `./artifacts/launchfast/campaigns/` + +## Strategy + +Kunzeโ€™s model favors: + +- broad and phrase coverage +- one ad group per campaign +- small keyword sets +- gap-opportunity terms where competitors rank poorly + +## Workflow + +### 1. Market research + +Run: + +```text +research_products(keyword="", focus="balanced", product_limit=20) +``` + +Collect top 10-15 competitor ASINs plus market context. + +### 2. Keyword research + +- Research competitor ASINs in manageable batches of 3-4. +- Prefer parallel tool calls where possible. +- Do not require delegation. + +Use: + +```text +amazon_keyword_research(asins=[...], limit=50, min_search_volume=300) +``` + +### 3. Build the keyword master list + +For each keyword compute: + +- overlap across ASIN batches +- search volume +- CPC +- purchase rate +- relevance +- competitor coverage +- gap-opportunity signal + +Then select: + +- Broad campaign keywords +- Phrase campaign keywords +- ASIN targets +- Category target placeholder if category ID is unknown + +### 4. Generate bulksheet + +Create: + +- Auto campaign +- Broad campaign +- Phrase campaign +- Category targeting campaign +- ASIN targeting campaign + +Use deterministic CSV generation with Python `csv.writer`. + +Use this exact Amazon Bulksheets 2.0 header and column order: + +```text +Product,Entity,Operation,Campaign Id,Ad Group Id,Portfolio Id,Ad Id,Keyword Id,Product Targeting Id,Campaign Name,Ad Group Name,Start Date,End Date,Targeting Type,State,Daily Budget,sku,asin,Ad Group Default Bid,Bid,Keyword Text,Match Type,Bidding Strategy,Placement,Percentage,Product Targeting Expression,Audience ID,Shopper Cohort Percentage,Shopper Cohort Type +``` + +Deterministic campaign layout: + +- Auto: 1 campaign, 1 ad group, 1 product ad, 4 auto targeting rows +- Broad: 1 campaign, 1 ad group, 1 product ad, up to 5 broad-match keywords +- Phrase: 1 campaign, 1 ad group, 1 product ad, up to 5 phrase-match keywords +- Category: 1 campaign, 1 ad group, 1 product ad, 1 category targeting row +- ASIN: 1 campaign, 1 ad group, 1 product ad, up to 15 ASIN target rows + +Required defaults: + +- start date: current date in `YYYYMMDD` +- bidding strategy: `Dynamic bids - down only` +- one ad group per campaign +- if category ID is unknown, emit a literal placeholder such as `[CATEGORY_ID]` + +Write to: + +`./artifacts/launchfast/campaigns/[product-name]-kunze-[YYYY-MM-DD].csv` + +### 5. Provide an operator summary + +Return: + +- campaign list +- selected keywords +- budget assumptions +- output file path + +If a category ID is missing, leave a clear placeholder and call it out explicitly. diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-full-research-loop/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-full-research-loop/SKILL.md new file mode 100644 index 0000000..c118d10 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-full-research-loop/SKILL.md @@ -0,0 +1,119 @@ +--- +name: launchfast-full-research-loop +description: | + End-to-end Codex-native Amazon FBA research workflow using LaunchFast MCP. + Use when the user wants a single report covering product research, IP risk, + supplier sourcing, and PPC keyword intelligence. + + Requires `research_products`, `ip_check_manage`, `supplier_research`, and + `amazon_keyword_research`. + +argument-hint: "[keyword]" +--- + +# LaunchFast Full Research Loop + +## Inputs + +If needed, ask once for: + +- keyword or keyword list +- target selling price +- first order quantity +- optional competitor ASINs +- optional report path + +Default report path: + +`./artifacts/launchfast/reports/launchfast-report-[keyword]-[YYYY-MM-DD].html` + +## Workflow + +### 1. Product research + +- Run `research_products` for each keyword with `focus="balanced"` and `product_limit=20`. +- Score each keyword using the same logic as `launchfast-product-research`. +- Pick winners for deeper analysis. + +### 2. IP check + +For promising keywords, run: + +```text +ip_check_manage(action="ip_conflict_check", keyword="") +ip_check_manage(action="trademark_search", keyword="") +``` + +Extract: + +- conflict level +- notable active marks +- patent concerns if present +- final risk posture: CLEAR, CAUTION, or BLOCKED + +### 3. Supplier research + +For the strongest keyword, run: + +```text +supplier_research(keyword="", goldSupplierOnly=true, tradeAssuranceOnly=true, maxResults=10) +``` + +Summarize the top suppliers with: + +- company name +- quality score +- price band +- MOQ +- years in business +- trust signals + +### 4. PPC research + +If you have competitor ASINs, or can responsibly infer 2-3 strong ASINs from product research, run: + +```text +amazon_keyword_research(asins=[...], limit=20) +``` + +Summarize: + +- keyword count +- top search-volume terms +- high-intent terms by purchase rate +- indicative CPCs +- suggested campaign structure + +If there are no usable ASINs, state that this phase was skipped. + +### 5. Build the report + +Create a standalone HTML report with: + +- executive verdict banner +- market scorecard +- product findings +- IP findings +- supplier findings +- PPC findings +- concise recommendation section + +Design should match the existing LaunchFast visual language: + +- clean light theme +- neutral palette +- card layout +- compact tables +- clear GO / INVESTIGATE / PASS styling + +Write the file to the requested path and report the final file location. + +## Output + +Always return: + +- overall verdict +- key blockers or strengths +- report path if the file was written + +Do not pad the response with generic โ€œnext stepsโ€ unless the evidence clearly supports a specific recommendation. diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-ppc-research/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-ppc-research/SKILL.md new file mode 100644 index 0000000..b674959 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-ppc-research/SKILL.md @@ -0,0 +1,128 @@ +--- +name: launchfast-ppc-research +description: | + Codex-native Amazon PPC keyword research using LaunchFast MCP. Use when the + user wants competitor keyword discovery, keyword tiering, or a ready-to-upload + Amazon Sponsored Products bulk file from 1-15 ASINs. + + Requires the LaunchFast MCP tool `amazon_keyword_research`. + +argument-hint: "[ASIN1] [ASIN2] [ASIN3]" +--- + +# LaunchFast PPC Research + +## Inputs + +If needed, ask once for: + +- 1-15 ASINs +- optional campaign name +- optional default CPC bid +- optional daily budget +- optional output path + +Defaults: + +- campaign name: `LaunchFast-PPC-[YYYY-MM-DD]` +- default bid: `0.75` +- daily budget: `25` +- output path: `./artifacts/launchfast/ppc/launchfast-ppc-[YYYY-MM-DD].tsv` + +## Workflow + +### 1. Run keyword research + +Run one keyword-research call across all ASINs when possible: + +```text +amazon_keyword_research(asins=[...], limit=50) +``` + +If the ASIN set is too large or results are unwieldy, batch them, but do not require delegation. + +### 2. Normalize and tier keywords + +For each keyword: + +- deduplicate across ASIN overlaps +- keep overlap count +- capture search volume, CPC, purchase rate, relevance, and ranking coverage + +Tiering: + +- Tier 1: high-value terms with strong overlap or standout volume and conversion +- Tier 2: mid-volume growth terms +- Tier 3: discovery and long-tail terms + +Match mapping: + +- Exact: Tier 1 +- Phrase: Tier 1 and Tier 2 +- Broad: Tier 2 and Tier 3 + +Bid guidance: + +- Exact: default bid * 1.2 +- Phrase: default bid * 1.0 +- Broad: default bid * 0.7 + +### 3. Present a preview + +Show: + +- ASINs analyzed +- unique keywords found +- tier breakdown +- top 15 keywords preview +- negative keywords or exclusions if obvious + +### 4. Generate the bulk file + +If the user wants the export, create the parent directory and write a TSV. + +Use a deterministic writer such as Python `csv.writer` with a tab delimiter. + +Required output: + +- one campaign +- ad groups split by tier and match type +- keyword rows with bids + +Default to this exact tab-separated header and column order: + +```text +Product Entity Operation Campaign ID Ad Group ID Portfolio ID Ad ID Keyword ID Product Targeting ID Campaign Name Ad Group Name Start Date End Date Targeting Type State Daily Budget SKU ASIN Ad Group Default Bid Bid Custom Text Campaign Type Targeting Expression +``` + +Deterministic campaign structure: + +- `Tier1-Exact`: Tier 1 keywords as Exact +- `Tier1-Phrase`: Tier 1 keywords as Phrase +- `Tier2-Phrase`: Tier 2 keywords as Phrase +- `Tier3-Broad`: Tier 2 and Tier 3 keywords as Broad + +Generate three row types only: + +- Campaign row: one per campaign +- Ad Group row: one per ad group +- Keyword row: one per keyword and match-type pair + +Use: + +- `Start Date`: current date in `YYYYMMDD` +- `Targeting Type`: `Manual` +- `State`: `enabled` +- `Campaign Type`: `Sponsored Products` + +If the user requests a different Amazon bulk format, switch only with explicit confirmation. + +## Output + +Default answer structure: + +- short summary of keyword landscape +- preview table +- export path and row count if a file was written + +If no export is requested, stop after the preview and recommendations. diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-product-research/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-product-research/SKILL.md new file mode 100644 index 0000000..372b961 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/launchfast-product-research/SKILL.md @@ -0,0 +1,102 @@ +--- +name: launchfast-product-research +description: | + Codex-native multi-keyword Amazon opportunity scan using LaunchFast MCP. + Use when the user wants to research 1-10 keywords, compare niches, or decide + whether a product idea is a GO, INVESTIGATE, or PASS. + + Requires the LaunchFast MCP tool `research_products`. + +argument-hint: "[keyword 1], [keyword 2], [keyword 3]" +--- + +# LaunchFast Product Research + +Use this skill for a fast, opinionated market scan across up to 10 keywords. + +## Inputs + +If missing, ask once for: + +- keywords to research +- optional target price band +- optional competition tolerance + +## Workflow + +### 1. Run research + +- Run `research_products` for each keyword. +- Prefer parallel tool calls when researching more than one keyword. +- Use `focus="balanced"` and `product_limit=20` unless the user asks otherwise. + +### 2. Extract core metrics per keyword + +From the response, compute: + +- products analyzed +- grade distribution +- median monthly revenue +- top product revenue +- average or median price +- average or median reviews +- brand concentration +- dominant brand + +### 3. Score the market + +Use this score out of 100: + +```text +score = + (% of products graded B5 or better) * 30 ++ (median revenue >= 8000 ? 30 : (median revenue / 8000) * 30) ++ (median reviews < 300 ? 20 : (300 / median reviews) * 20) ++ (median price between 18 and 60 ? 20 : 10) +``` + +Competition bands: + +- Low: median reviews < 200 +- Medium: median reviews 200-800 +- High: median reviews > 800 + +Verdicts: + +- GO: score >= 65 +- INVESTIGATE: score 40-64 +- PASS: score < 40 + +### 4. Present results + +Always show: + +- a ranked summary table for all keywords +- a short deep dive for the top 3 + +Use this table shape: + +```markdown +## Product Opportunity Scan + +| Rank | Keyword | Score | Market Grade | Top Revenue | Avg Price | Competition | Verdict | +|------|---------|-------|--------------|-------------|-----------|-------------|---------| +``` + +For each top-3 keyword include: + +- products analyzed +- grade distribution +- revenue range +- price range +- review range +- best product snapshot +- one-sentence key insight +- risk flags +- verdict with 1-2 sentence rationale + +## Notes + +- If a keyword has missing or zero search volume, explicitly call that out. +- If the results look too narrow or too broad, suggest the better keyword variant inline. +- Do not force a follow-up question at the end; only recommend next actions when the result is borderline or strong enough to justify it. diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/product-research/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/product-research/SKILL.md new file mode 100644 index 0000000..f834556 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/product-research/SKILL.md @@ -0,0 +1,137 @@ +--- +name: product-research +description: | + Deep Codex-native Amazon FBA product validation using LaunchFast MCP and the + LegacyX criteria. Use when the user wants a serious viability review for a + keyword, niche, or adjacent niche expansion. +--- + +# Amazon FBA Product Research + +This skill is the deeper, criteria-driven version of `launchfast-product-research`. + +## Core criteria + +Evaluate every market against these baselines: + +| Criteria | Threshold | +|---|---| +| Total niche revenue | > $200,000/month | +| Average price | >= $25, ideally >= $40 | +| Average reviews | <= 500 | +| Revenue per seller | >= $5,000/month | +| Top-seller dominance | top 2-3 sellers < 50% of revenue | +| Search volume | must exist | +| Estimated margin | >= 30% before ad costs | + +Large-market exception: + +- If niche revenue is above $1M, higher review counts can still be acceptable when multiple sellers under 200 reviews are doing strong revenue. + +## Workflow + +### 1. Initial scan + +Run: + +```text +research_products(keyword="", focus="balanced", product_limit=20) +``` + +Extract: + +- search volume +- average price +- average reviews +- opportunity score +- market grade +- brand concentration +- dominant brand +- total niche revenue +- average revenue per seller +- top-seller share + +### 2. Financial trend check + +Run: + +```text +research_products(keyword="", focus="financial", product_limit=20) +``` + +Look for: + +- growing vs stable vs declining products +- average MoM growth +- short-term momentum using 7d trend fields + +### 3. Listing quality check + +Run: + +```text +research_products(keyword="", focus="titles", product_limit=10) +``` + +Look for: + +- low listing quality scores with high revenue +- listing quality gaps +- weak copy or obvious differentiation openings + +### 4. Keyword validation + +Pick 2-3 relevant ASINs and run: + +```text +amazon_keyword_research(asins=["ASIN1", "ASIN2", "ASIN3"], limit=20) +``` + +Evaluate: + +- keyword diversity +- CPC and sponsored density +- purchase rate +- obvious ranking gaps + +### 5. Profitability estimate + +Present a conservative estimate: + +```text +Selling Price +- Amazon Fees (~15%) +- Manufacturing +- Shipping += Estimated Profit per Unit += Estimated Margin % +``` + +If manufacturing cost is unknown, say so and state the assumption used. + +## Output format + +Use a scorecard first: + +```markdown +## Market Scorecard: [keyword] + +| Criteria | Threshold | Actual | Status | +|---|---|---|---| +``` + +Then include: + +- market grade +- opportunity score +- trend summary +- verdict: VIABLE, MARGINAL, or NOT RECOMMENDED +- concise rationale + +## Rabbit-hole expansion + +Use adjacent-niche exploration only when it is helpful: + +- identify variations from the first result set +- rerun `research_products` on the most promising adjacent keywords +- keep the branching tight; do not explode the scope without user intent diff --git a/plugins/BlockchainHB/launchfast_codex_plugin/skills/wilco-ad-setup/SKILL.md b/plugins/BlockchainHB/launchfast_codex_plugin/skills/wilco-ad-setup/SKILL.md new file mode 100644 index 0000000..78f8650 --- /dev/null +++ b/plugins/BlockchainHB/launchfast_codex_plugin/skills/wilco-ad-setup/SKILL.md @@ -0,0 +1,117 @@ +--- +name: wilco-ad-setup +description: | + Codex-native Amazon PPC setup workflow using Wilco's exact-match and + analytics-first strategy. Use when the user wants stricter keyword control, + exact-match campaigns, and a LaunchFast-driven bulk-sheet export. +--- + +# Wilco Ad Setup + +## Inputs + +Ask once for: + +- main keyword +- product SKU +- optional product name +- optional budget level +- optional output path + +Defaults: + +- budget level: conservative +- output directory: `./artifacts/launchfast/campaigns/` + +## Strategy + +Wilcoโ€™s model favors: + +- exact match only for manual keyword campaigns +- tight budget isolation +- proven converting keywords +- strong emphasis on purchase rate and competitor coverage + +## Workflow + +### 1. Market research + +Run: + +```text +research_products(keyword="", focus="balanced", product_limit=20) +``` + +Capture top 10-12 ASINs and market context. + +### 2. Keyword research + +- batch ASINs in groups of 3-4 +- prefer parallel tool calls when practical +- do not require delegation + +Use: + +```text +amazon_keyword_research(asins=[...], limit=50, min_search_volume=300) +``` + +### 3. Score keywords + +Rank keywords with a weighted score based on: + +- purchase rate +- competitor coverage +- search volume +- relevance + +Prioritize keywords where multiple competitors already rank well. + +Select: + +- Exact A: top converters +- Exact B: volume converters +- Exact C: niche converters +- Product targets: top competitor ASINs + +### 4. Generate bulksheet + +Create: + +- Auto campaign +- Product targeting campaign +- 3 exact-match manual campaigns + +Use Python `csv.writer` and write to: + +Use this exact Amazon Bulksheets 2.0 header and column order: + +```text +Product,Entity,Operation,Campaign Id,Ad Group Id,Portfolio Id,Ad Id,Keyword Id,Product Targeting Id,Campaign Name,Ad Group Name,Start Date,End Date,Targeting Type,State,Daily Budget,sku,asin,Ad Group Default Bid,Bid,Keyword Text,Match Type,Bidding Strategy,Placement,Percentage,Product Targeting Expression,Audience ID,Shopper Cohort Percentage,Shopper Cohort Type +``` + +Deterministic campaign layout: + +- Auto: 1 campaign, 1 ad group, 1 product ad, 4 auto targeting rows +- Product targeting: 1 campaign, 1 ad group, 1 product ad, up to 10 ASIN target rows +- Exact A: 1 campaign, 1 ad group, 1 product ad, up to 5 exact-match keywords +- Exact B: 1 campaign, 1 ad group, 1 product ad, up to 5 exact-match keywords +- Exact C: 1 campaign, 1 ad group, 1 product ad, up to 5 exact-match keywords + +Required defaults: + +- start date: current date in `YYYYMMDD` +- bidding strategy: `Dynamic bids - down only` +- one ad group per campaign +- exact match for all three manual keyword campaigns + +`./artifacts/launchfast/campaigns/[product-name]-wilco-[YYYY-MM-DD].csv` + +### 5. Return summary + +Include: + +- why Wilco is a better fit or not for this niche +- keyword selection logic +- bids and budget assumptions +- export path diff --git a/plugins/JuliusBrussee/blueprint/.codex-plugin/plugin.json b/plugins/JuliusBrussee/blueprint/.codex-plugin/plugin.json new file mode 100644 index 0000000..cabd88b --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/.codex-plugin/plugin.json @@ -0,0 +1,45 @@ +{ + "name": "bp", + "version": "2.0.0", + "description": "Blueprint Framework for Codex and Claude Code. Draft blueprints, architect build sites, and execute adaptive build waves with validation and peer review.", + "author": { + "name": "Julius Brussee", + "url": "https://github.com/JuliusBrussee" + }, + "homepage": "https://github.com/JuliusBrussee/sdd-os", + "repository": "https://github.com/JuliusBrussee/sdd-os", + "license": "MIT", + "keywords": [ + "blueprint", + "agents", + "codex", + "claude-code", + "spec-driven-development" + ], + "skills": "./skills/", + "agents": "./agents/", + "commands": "./commands/", + "interface": { + "displayName": "Blueprint", + "shortDescription": "Blueprint-driven software delivery for coding agents", + "longDescription": "Turn natural language into blueprints, blueprints into build sites, and build sites into validated code with adaptive parallel execution.", + "developerName": "Julius Brussee", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write" + ], + "composerIcon": "./.codex-plugin/icon.svg", + "logo": "./.codex-plugin/logo.svg", + "screenshots": [], + "privacyPolicyURL": "./.codex-plugin/PRIVACY.md", + "termsOfServiceURL": "./.codex-plugin/TERMS.md", + "websiteURL": "https://github.com/JuliusBrussee/sdd-os", + "defaultPrompt": [ + "Draft blueprints for a feature from my repo context.", + "Architect the current blueprints into a build site.", + "Build the current site with adaptive parallel work packets." + ], + "brandColor": "#1F4B99" + } +} diff --git a/plugins/JuliusBrussee/blueprint/.codexignore b/plugins/JuliusBrussee/blueprint/.codexignore new file mode 100644 index 0000000..80421da --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/.codexignore @@ -0,0 +1,21 @@ +# === Dev / IDE === +.claude/ +.superpowers/ +.DS_Store +.git/ + +# === Build artifacts & dependencies === +scripts/node_modules/ +scripts/package-lock.json + +# === Go build (binary is platform-specific, users build from source) === +blueprint + +# === Internal docs & planning (not needed by consumers) === +docs/superpowers/ +TODO.md + +# === Context working directories (populated per-project, not plugin content) === +context/refs/ +context/impl/archive/ +context/sites/ diff --git a/plugins/JuliusBrussee/blueprint/LICENSE b/plugins/JuliusBrussee/blueprint/LICENSE new file mode 100644 index 0000000..d8c0ee8 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Julius Brussee + +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/plugins/JuliusBrussee/blueprint/README.md b/plugins/JuliusBrussee/blueprint/README.md new file mode 100644 index 0000000..d3efc7c --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/README.md @@ -0,0 +1,578 @@ +

+ Blueprint +

+ +

Specification-driven development for AI coding agents

+ +

+ A Claude Code plugin that turns natural language into blueprints,
+ blueprints into parallel build plans, and build plans into working software โ€”
+ with automated iteration, validation, and dual-model adversarial review via Codex. +

+ +

+ MIT License + Claude Code Plugin + Version 2.1.0 +

+ +

+ Install · + How It Works · + Quick Start · + Parallel Execution · + Codex Review · + Commands · + Methodology · + Examples +

+ +--- + +## The Problem + +AI coding agents are powerful, but they fail in predictable ways: + +- **They lose context.** Ask an agent to build a full-stack feature and it forgets what it said three steps ago. +- **They skip validation.** Code gets written but never verified against the original intent. +- **They can't parallelize.** One agent, one task, one branch โ€” even when the work is independent. +- **They don't iterate.** A single pass produces a rough draft, not production code. + +Blueprint fixes all of this. + +--- + +## The Idea + +Instead of prompting an agent and hoping for the best, Blueprint introduces a **specification layer** between your intent and the code. You describe what you want. The system decomposes it into domain blueprints with numbered requirements and testable acceptance criteria. Then it builds from those blueprints โ€” not from memory, not from vibes โ€” in an automated loop that validates every step. + +``` + โ”Œโ”€โ”€โ”€ Task 1 โ”€โ”€โ”€ Agent A โ”€โ”€โ”€โ” + โ”‚ โ”‚ +You โ”€โ”€ /bp:draft โ”€โ”€โ–บ Blueprints โ”€โ”€ /bp:architect โ”€โ”€โ–บ Build Site โ”€โ”€โ”คโ”€โ”€โ”€ Task 2 โ”€โ”€โ”€ Agent B โ”€โ”€โ”€โ”คโ”€โ”€โ–บ done + โ”‚ โ”‚ + โ””โ”€โ”€โ”€ Task 3 โ”€โ”€โ”€ Agent C โ”€โ”€โ”€โ”˜ +``` + +The blueprints are the source of truth. Agents read them, build from them, and validate against them. When something breaks, the system traces the failure back to the blueprint โ€” not the code. + +--- + +## Without Blueprint vs. With Blueprint + + + + + + + +
Without BlueprintWith Blueprint
+ +``` +> Build me a task management API + + (agent writes 2000 lines) + (no tests) + (forgot the auth middleware) + (wrong database schema) + (you spend 3 hours fixing it) +``` + +One shot. No validation. No traceability. +The agent guessed what you wanted. + + + +``` +> /bp:draft + 4 blueprints, 22 requirements, 69 criteria + +> /bp:architect + 34 tasks across 5 dependency tiers + +> /bp:build + 18 iterations โ€” each validated against + the blueprint before committing + + BLUEPRINT COMPLETE +``` + +Every line of code traces to a requirement. +Every requirement has acceptance criteria. + +
+ +--- + +## Install + +```bash +git clone https://github.com/JuliusBrussee/blueprint.git ~/.blueprint +cd ~/.blueprint && ./install.sh +``` + +This registers the Blueprint plugin with Claude Code, syncs it into your local Codex plugin marketplace, links Codex prompt files into `~/.codex/prompts/`, and installs the `blueprint` CLI. Restart Claude Code and Codex after installing. + +**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, macOS/Linux. + +**Optional:** [Codex](https://github.com/openai/codex) (`npm install -g @openai/codex`) โ€” enables adversarial review at the design, build, and command levels. Blueprint works without it, but Codex makes it significantly harder to ship flawed specs and broken code. + +--- + +## How It Works + +Blueprint follows four phases โ€” **Draft, Architect, Build, Inspect** โ€” each driven by a slash command inside Claude Code. An optional **Research** phase grounds the design in real evidence before blueprints are written. A standalone `/bp:design` command creates and maintains a **DESIGN.md** design system that becomes a cross-cutting constraint enforced throughout all phases. + +``` + RESEARCH DRAFT ARCHITECT BUILD INSPECT + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”€โ”€โ”€โ”€โ”€ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”€โ”€โ”€โ”€โ”€ โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + (optional) "What are we Break into tasks, Auto-parallel: Gap analysis: + Multi-agent building?" map dependencies, /bp:build built vs. + codebase + organize into groups work intended. + web research Produces: tiered build site into adaptive Peer review. + blueprints + dependency graph subagent packets Trace to specs. + Produces: with R-numbered tier by tier + research brief requirements Produces: Produces: + in context/refs task graph Codex reviews findings report + Codex challenges every tier gate + the design (speculative + + synchronous) + + โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” + /bp:design (standalone) โ†’ DESIGN.md โ†’ design tokens referenced in blueprints + tasks + design-reviewer enforces across build + inspect + โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +``` + +### 0. Research โ€” ground the design (optional) + +``` +/bp:research "build a Verse compiler targeting WASM" +``` + +Dispatches 2โ€“8 parallel subagents to explore the codebase and search the web for current best practices, library landscape, reference implementations, and common pitfalls. A synthesizer agent cross-validates findings and produces a research brief in `context/refs/`. Research is also offered inline during `/bp:draft` when the project involves unfamiliar technology or architectural decisions with multiple viable approaches. + +### /bp:design โ€” establish the design system (standalone) + +``` +/bp:design +``` + +Creates or imports a **DESIGN.md** design system that becomes a cross-cutting constraint layer across the entire pipeline. Once present, every blueprint references its design tokens, every task carries a Design Ref, and every build result is audited for design violations. + +Four sub-commands: + +- `/bp:design create` โ€” generate a new DESIGN.md from scratch via guided Q&A +- `/bp:design import` โ€” extract a DESIGN.md from an existing codebase +- `/bp:design audit` โ€” check current implementation against DESIGN.md, report violations +- `/bp:design update` โ€” revise DESIGN.md and log the change to `context/designs/design-changelog.md` + +When DESIGN.md exists, the **design-reviewer agent** validates UI changes during build and inspect, flagging `DESIGN VIOLATION` statuses for any task that drifts from the tokenized system. Design changes are tracked in a changelog so intent is never lost across build cycles. + +### 1. Draft โ€” define the what + +``` +/bp:draft +``` + +You describe what you're building in natural language. Blueprint decomposes it into **domain blueprints** โ€” structured documents with numbered requirements (R1, R2, ...) and testable acceptance criteria. Each blueprint is stack-independent and human-readable. + +When the project would benefit from it, the draft phase offers to run [deep research](#0-research--ground-the-design-optional) before design Q&A โ€” grounding clarifying questions and approach proposals in real evidence rather than LLM priors. + +After the internal reviewer approves, blueprints are sent to Codex for a [design challenge](#design-challenge--catch-spec-flaws-before-building) โ€” an adversarial review that catches decomposition flaws, missing requirements, and ambiguous criteria before any code is written. + +For existing codebases, `/bp:draft --from-code` reverse-engineers blueprints from your code and identifies gaps. + +### 2. Architect โ€” plan the order + +``` +/bp:architect +``` + +Reads all blueprints, breaks requirements into tasks, maps dependencies, and organizes everything into a **tiered build site** โ€” a dependency graph where Tier 0 has no dependencies, Tier 1 depends only on Tier 0, and so on. This is what the build loop consumes. + +### 3. Build โ€” run the loop + +``` +/bp:build +``` + +The Ralph Loop. Each iteration: + +``` + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ โ”‚ + โ”‚ Read build site โ†’ Find next unblocked task โ”‚ + โ”‚ โ”‚ โ”‚ + โ”‚ โ–ผ โ”‚ + โ”‚ Load relevant blueprint + acceptance criteria โ”‚ + โ”‚ โ”‚ โ”‚ + โ”‚ โ–ผ โ”‚ + โ”‚ Implement the task โ”‚ + โ”‚ โ”‚ โ”‚ + โ”‚ โ–ผ โ”‚ + โ”‚ Validate (build + tests + acceptance criteria) โ”‚ + โ”‚ โ”‚ โ”‚ + โ”‚ โ”œโ”€โ”€ PASS โ†’ commit โ†’ mark done โ†’ next task โ”€โ”€โ” โ”‚ + โ”‚ โ”‚ โ”‚ โ”‚ + โ”‚ โ””โ”€โ”€ FAIL โ†’ diagnose โ†’ fix โ†’ revalidate โ”‚ โ”‚ + โ”‚ โ”‚ โ”‚ + โ”‚ โ—„โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ + โ”‚ โ”‚ + โ”‚ Loop until: all tasks done OR iteration limit reached โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +At every tier boundary, [Codex adversarial review](#codex-adversarial-review) gates advancement โ€” P0/P1 findings must be fixed before the next tier starts. With speculative review enabled (default), this adds near-zero latency because the review runs in the background while the next tier builds. + +### 4. Inspect โ€” verify the result + +``` +/bp:inspect +``` + +Gap analysis compares what was built against what was specified. Peer review checks for bugs, security issues, and missed requirements. Everything traced back to blueprint requirements. + +--- + +## Quick Start + +**Greenfield project:** + +``` +> /bp:draft +What are you building? + +> A REST API for task management. Users, projects, tasks with priorities + and due dates, assignments. PostgreSQL. + +Created 4 blueprints (22 requirements, 69 acceptance criteria) +Next: /bp:architect + +> /bp:architect +Generated build site: 34 tasks, 5 tiers +Next: /bp:build + +> /bp:build +Loop activated โ€” 34 tasks, 20 max iterations. +... +All tasks done. Build passes. Tests pass. +BLUEPRINT COMPLETE โ€” 34 tasks in 18 iterations. +``` + +**Existing codebase:** + +``` +> /bp:draft --from-code +Exploring codebase... Next.js 14, Prisma, NextAuth. +Created 6 blueprints โ€” 4 requirements are gaps (not yet implemented). + +> /bp:architect --filter collaboration +Generated build site: 8 tasks, 3 tiers + +> /bp:build +Loop activated โ€” 8 tasks. +... +BLUEPRINT COMPLETE โ€” 8 tasks in 8 iterations. +``` + +See [example.md](example.md) for full annotated conversations. + +--- + +## Parallel Execution + +`/bp:build` automatically parallelizes. When multiple tasks are ready (no unmet dependencies), it groups them into a few coherent work packets based on shared files, subsystem, and task complexity, then runs those packets in parallel. + +``` +> /bp:build +โ•โ•โ• Wave 1 โ•โ•โ• +3 task(s) ready: + T-001: Database schema (tier 0, deps: none) + T-002: Auth middleware (tier 0, deps: none) + T-003: Config loader (tier 0, deps: none) + +Dispatching 2 grouped subagents... +All 3 tasks complete. Merging... + +โ•โ•โ• Wave 2 โ•โ•โ• +2 task(s) ready: + T-004: User endpoints (tier 1, deps: T-001, T-002) + T-005: Health check (tier 1, deps: T-003) + +Dispatching 2 grouped subagents... +All done. + +โ•โ•โ• BUILD COMPLETE โ•โ•โ• +Waves: 2 | Tasks: 5/5 +``` + +How it works: +- Reads the build site and computes the **frontier** โ€” all tasks whose dependencies are complete +- Groups the ready frontier into coherent work packets before delegating +- Uses parallel subagents where file ownership and task size make that worthwhile +- After all complete, merges results and computes the next frontier +- Repeats wave-by-wave until all tasks are done โ€” no manual intervention between tiers + +Circuit breakers prevent infinite loops: 3 test failures โ†’ task marked BLOCKED, all tasks blocked โ†’ stop and report. + +--- + +## Codex Adversarial Review + +Blueprint uses [Codex](https://github.com/openai/codex) (OpenAI's coding agent) as an adversarial reviewer โ€” a second model with a fundamentally different perspective that catches blind spots Claude cannot see in its own output. This dual-model approach operates at three levels: + +### Design Challenge โ€” catch spec flaws before building + +After Claude drafts blueprints and the internal reviewer approves them, the entire blueprint set is sent to Codex for a **design challenge** โ€” an adversarial review focused exclusively on architecture-level concerns: + +``` + Claude drafts Blueprint Codex challenges User reviews + blueprints โ”€โ”€โ”€โ”€โ”€โ”€โ–บ reviewer approves โ”€โ”€โ”€โ”€โ”€โ”€โ–บ the design โ”€โ”€โ”€โ”€โ”€โ”€โ–บ blueprints + findings + โ”‚ + Checks: โ”‚ + โ€ข Domain decomposition quality + โ€ข Missing requirements + โ€ข Ambiguous acceptance criteria + โ€ข Implicit assumptions + โ€ข Cross-domain coherence +``` + +Codex returns structured findings categorized as **critical** (must fix before building) or **advisory** (worth considering). Critical findings trigger an auto-fix loop โ€” Claude addresses them, Codex re-challenges, up to 2 cycles. Advisory findings are presented alongside blueprints at the user review gate. + +The design challenge is purpose-built to prohibit implementation feedback. No framework suggestions, no file path opinions โ€” only design-level concerns that would cause real problems during the build phase. + +### Tier Gate โ€” catch code defects between build tiers + +During `/bp:build`, every completed tier triggers a Codex adversarial code review before advancing: + +``` + โ•โ•โ• Tier 0 Complete โ•โ•โ• + Codex reviews diff (T-001, T-002, T-003) ... + Review: 2 findings (1 P0, 1 P3) + Gate: BLOCKED โ†’ fix cycle 1/2 + + Fixing P0: nil pointer in auth middleware ... + Re-review ... + Gate: PROCEED + + โ•โ•โ• Tier 1 starting โ•โ•โ• +``` + +The **severity-based gate** classifies findings by impact: + +| Severity | Behavior | +|----------|----------| +| P0 (critical) | Blocks tier advancement. Fix task generated automatically. | +| P1 (high) | Blocks tier advancement. Fix task generated automatically. | +| P2 (medium) | Deferred. Logged but does not block. | +| P3 (low) | Deferred. Logged but does not block. | + +Gate modes are configurable: `severity` (default โ€” P0/P1 block), `strict` (all findings block), `permissive` (nothing blocks), or `off`. + +The review-fix cycle runs up to 2 iterations per tier. After that, the build advances with a warning โ€” the system never deadlocks. + +### Speculative Review โ€” eliminate gate latency + +By default, Blueprint runs the Codex review of the *previous* tier in the background while Claude builds the *current* tier: + +``` + Tier 0 complete โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ Tier 1 complete + โ”‚ โ”‚ + โ””โ”€โ”€ Codex reviews Tier 0 (background) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บโ”‚ + โ”‚ + Results ready โ—„โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + before gate runs +``` + +When the current tier finishes and the gate checks for the previous tier's review, the results are already available โ€” cutting tier gate latency to near-zero. If the background review isn't done yet, the system waits (with a configurable timeout) and falls back to synchronous review if needed. + +### Command Safety Gate + +A PreToolUse hook intercepts every Bash command before execution and classifies its safety: + +``` + Agent runs bash command + โ”‚ + โ–ผ + Fast-path check โ”€โ”€โ–บ allowlist (50+ safe commands) โ†’ approve + โ”‚ โ””โ–บ blocklist (rm -rf, force push, DROP TABLE, ...) โ†’ block + โ”‚ + โ–ผ (ambiguous) + Codex classifies โ”€โ”€โ–บ safe โ†’ approve + โ”‚ โ””โ–บ warn โ†’ approve + log + โ”‚ โ””โ–บ block โ†’ prevent execution + โ”‚ + โ–ผ (cached) + Verdict cache โ”€โ”€โ–บ normalized pattern match โ†’ reuse verdict +``` + +The gate integrates with Claude Code's permission system โ€” commands already allowed or blocked in settings bypass the gate entirely. Verdicts are cached by normalized command pattern within the session to avoid redundant API calls. When Codex is unavailable, the gate falls back to static rules only โ€” it never blocks a command solely because the classifier is unreachable. + +### Graceful degradation + +All Codex features are **additive**. When Codex is not installed: + +- Design challenge is skipped โ€” the internal blueprint reviewer still runs +- Tier gate is skipped โ€” the build loop proceeds without review pauses +- Command gate falls back to static allowlist/blocklist only +- A one-time install nudge appears: `Tip: Install Codex for adversarial code review` + +Blueprint works the same as before. Codex makes it harder to ship bad blueprints and bad code. + +### Configuration + +Blueprint settings can live in two places: + +- User default: `~/.blueprint/config` +- Project override: `.blueprint/config` + +Precedence is: project override > user default > built-in default. + +| Setting | Values | Default | Purpose | +|---------|--------|---------|---------| +| `bp_model_preset` | `expensive` `quality` `balanced` `fast` | `quality` | Resolve `reasoning`, `execution`, and `exploration` models for Blueprint commands | +| `codex_review` | `auto` `off` | `auto` | Enable/disable Codex reviews | +| `codex_model` | model string | (Codex default) | Model for Codex calls | +| `tier_gate_mode` | `severity` `strict` `permissive` `off` | `severity` | How findings gate tier advancement | +| `command_gate` | `all` `interactive` `off` | `all` | Which sessions get command gating | +| `command_gate_timeout` | milliseconds | `3000` | Timeout for Codex safety classification | +| `speculative_review` | `on` `off` | `on` | Background review of previous tier | +| `speculative_review_timeout` | seconds | `300` | Max wait for speculative results | + +Built-in model presets: + +| Preset | Reasoning | Execution | Exploration | +|--------|-----------|-----------|-------------| +| `expensive` | `opus` | `opus` | `opus` | +| `quality` | `opus` | `opus` | `sonnet` | +| `balanced` | `opus` | `sonnet` | `haiku` | +| `fast` | `sonnet` | `sonnet` | `haiku` | + +Use `/bp:config` to inspect or change the active preset. + +Examples: + +```bash +/bp:config +/bp:config list +/bp:config preset balanced +/bp:config preset fast --global +``` + +--- + +## Commands + +### Claude Code slash commands + +| Command | Phase | Description | +|---------|-------|-------------| +| `/bp:research` | Research | Deep multi-agent research โ€” codebase + web, produces research brief | +| `/bp:design` | Design | Create, import, audit, or update DESIGN.md โ€” establishes a tokenized design system enforced across the pipeline | +| `/bp:draft` | Draft | Decompose requirements into domain blueprints (offers research if warranted) | +| `/bp:architect` | Architect | Generate a tiered build site from blueprints | +| `/bp:build` | Build | Auto-parallel build โ€” dispatches independent tasks concurrently, progresses through tiers autonomously | +| `/bp:inspect` | Inspect | Gap analysis + peer review against blueprints | +| `/bp:config` | โ€” | Show or update the active Blueprint execution preset | +| `/bp:codex-review` | โ€” | Run standalone Codex adversarial review on current diff | +| `/bp:progress` | โ€” | Check build site progress | +| `/bp:gap-analysis` | โ€” | Compare built vs. intended | +| `/bp:revise` | โ€” | Trace manual fixes back into blueprints | +| `/bp:help` | โ€” | Show usage guide | + +### CLI commands + +| Command | Description | +|---------|-------------| +| `blueprint version` | Print version | + +--- + +## File Structure + +``` +context/ +โ”œโ”€โ”€ blueprints/ # Domain blueprints (persist across cycles) +โ”‚ โ”œโ”€โ”€ blueprint-overview.md +โ”‚ โ””โ”€โ”€ blueprint-{domain}.md +โ”œโ”€โ”€ designs/ # Design system artifacts +โ”‚ โ”œโ”€โ”€ DESIGN.md # Tokenized design system (colors, typography, spacing, components) +โ”‚ โ””โ”€โ”€ design-changelog.md # Audit log of design decisions and changes +โ”œโ”€โ”€ sites/ # Build sites (one per plan) +โ”‚ โ”œโ”€โ”€ build-site-*.md +โ”‚ โ””โ”€โ”€ archive/ +โ”œโ”€โ”€ impl/ # Implementation tracking +โ”‚ โ”œโ”€โ”€ impl-{domain}.md +โ”‚ โ”œโ”€โ”€ impl-review-findings.md # Codex review findings ledger +โ”‚ โ”œโ”€โ”€ impl-speculative-log.md # Speculative review timing data +โ”‚ โ”œโ”€โ”€ loop-log.md +โ”‚ โ””โ”€โ”€ archive/ +โ””โ”€โ”€ refs/ # Reference materials (PRDs, API docs) + โ”œโ”€โ”€ research-brief-{topic}.md # Synthesized research brief + โ””โ”€โ”€ research-{topic}/ # Raw findings + findings board + +scripts/ +โ”œโ”€โ”€ bp-config.sh # Canonical Blueprint config + model preset resolver +โ”œโ”€โ”€ codex-detect.sh # Codex binary and plugin detection +โ”œโ”€โ”€ codex-config.sh # Backward-compatible wrapper for bp-config.sh +โ”œโ”€โ”€ codex-review.sh # Adversarial code review invocation +โ”œโ”€โ”€ codex-findings.sh # Structured finding management +โ”œโ”€โ”€ codex-gate.sh # Severity-based tier gating + fix cycle +โ”œโ”€โ”€ codex-design-challenge.sh # Design challenge for blueprint drafts +โ”œโ”€โ”€ codex-speculative.sh # Background speculative review pipeline +โ””โ”€โ”€ command-gate.sh # PreToolUse command safety gate +``` + +--- + +## Methodology + +Blueprint is built on a simple observation: LLMs are non-deterministic, but software engineering doesn't have to be. By applying the **scientific method** โ€” hypothesize, test, observe, refine โ€” we extract reliable outcomes from a stochastic process. + +| Concept | Role | +|---------|------| +| **Blueprints** | The hypothesis โ€” what you expect the software to do | +| **Validation gates** | Controlled conditions โ€” build, tests, acceptance criteria | +| **Convergence loops** | Repeated trials โ€” iterate until stable | +| **Implementation tracking** | Lab notebook โ€” what was tried, what worked, what failed | +| **Revision** | Update the hypothesis โ€” trace bugs back to blueprints | + +The plugin ships with 9 specialized agents (including a **design-reviewer** that validates UI changes against DESIGN.md), a multi-agent research system, and 15 deep-dive skills covering the full methodology. When Codex is installed, the system operates as a **dual-model architecture** โ€” Claude builds and Codex reviews โ€” catching classes of errors that single-model self-review cannot detect. + +
+View all skills + +- **[Design System](skills/design-system)** โ€” how to create and maintain a DESIGN.md that agents enforce +- **[UI Craft](skills/ui-craft)** โ€” component patterns, animation playbook, accessibility checklist, and review checklist for UI work +- **[Blueprint Writing](skills/blueprint-writing)** โ€” how to write blueprints agents can consume +- **[Convergence Monitoring](skills/convergence-monitoring)** โ€” detecting when iterations plateau +- **[Peer Review](skills/peer-review)** โ€” six modes for cross-model review +- **[Validation-First Design](skills/validation-first)** โ€” every requirement must be verifiable +- **[Context Architecture](skills/context-architecture)** โ€” progressive disclosure for agent context +- **[Revision](skills/revision)** โ€” tracing bugs upstream to blueprints +- **[Brownfield Adoption](skills/brownfield-adoption)** โ€” adding Blueprint to an existing codebase +- **[Speculative Pipeline](skills/speculative-pipeline)** โ€” overlapping phases for faster builds +- **[Prompt Pipeline](skills/prompt-pipeline)** โ€” designing the prompts that drive each phase +- **[Implementation Tracking](skills/impl-tracking)** โ€” living records of build progress +- **[Documentation Inversion](skills/documentation-inversion)** โ€” docs for agents, not just humans +- **[Peer Review Loop](skills/peer-review-loop)** โ€” combining Ralph Loop with cross-model review +- **[Core Methodology](skills/methodology)** โ€” the full DABI lifecycle + +
+ +--- + +## Why "Blueprint" + +Most AI coding tools treat the agent as a black box โ€” you prompt, it generates, you hope. Blueprint inverts this. **The specification is the product. The code is a derivative.** When the spec is clear, the code follows. When the code is wrong, the spec tells you why. + +This matters because AI agents are getting better every month, but the fundamental problem remains: without a specification, there's nothing to validate against. Blueprint gives every agent โ€” current and future โ€” a contract to build from and a standard to meet. + +With Codex adversarial review, Blueprint goes further: a second model with different training and different blind spots reviews both the specification and the implementation. Two models disagreeing is a signal. Two models agreeing is confidence. + +--- + +## License + +MIT diff --git a/plugins/JuliusBrussee/blueprint/SECURITY.md b/plugins/JuliusBrussee/blueprint/SECURITY.md new file mode 100644 index 0000000..895c507 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in this project, please report it responsibly. + +**Do not open a public issue.** Instead, email **security@juliusbr.com** with: + +- A description of the vulnerability +- Steps to reproduce +- Any relevant logs or screenshots + +You can expect an initial response within 72 hours. We will work with you to understand the issue and coordinate a fix before any public disclosure. + +## Supported Versions + +| Version | Supported | +| ------- | --------- | +| latest | Yes | + +## Disclosure Policy + +We follow coordinated disclosure. Once a fix is available, we will publish a security advisory and credit the reporter (unless they prefer to remain anonymous). diff --git a/plugins/JuliusBrussee/blueprint/skills/blueprint-writing/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/blueprint-writing/SKILL.md new file mode 100644 index 0000000..1f867d1 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/blueprint-writing/SKILL.md @@ -0,0 +1,402 @@ +--- +name: blueprint-writing +description: | + How to write Blueprint-quality blueprints that AI agents can consume effectively. Covers + implementation-agnostic blueprint design, testable acceptance criteria, hierarchical structure, + cross-referencing, blueprint templates, greenfield and rewrite patterns, blueprint compaction, and gap analysis. + Trigger phrases: "write blueprints", "create blueprints", "blueprint this out", + "define requirements for agents", "how to write blueprints for AI" +--- + +# Blueprint Writing + +## Core Principle: Blueprints Describe WHAT, Not HOW + +Blueprints are **implementation-agnostic**. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture. + +This is the fundamental distinction in Blueprint: +- **Blueprints** = WHAT must be true (framework-agnostic, durable, portable) +- **Plans** = HOW to build it (framework-specific, derived from blueprints) +- **Code** = the implementation (generated from plans, validated against blueprints) + +### Why Implementation-Agnostic? + +When blueprints avoid prescribing HOW, they become: +- **Portable** โ€” the same blueprints can drive implementations in different frameworks +- **Durable** โ€” blueprints survive technology migrations +- **Testable** โ€” acceptance criteria are about behavior, not implementation details +- **Reusable** โ€” the same blueprints work for greenfield, rewrites, and cross-framework evaluation + +**Bad blueprint requirement:** "Use React useState hook to manage form state" +**Good blueprint requirement:** "Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values." + +--- + +## Every Requirement Needs Testable Acceptance Criteria + +This is the single most important rule in Blueprint writing. If an agent cannot automatically validate a requirement, that requirement will not be met. + +### The Validation-First Rule + +Every requirement must answer: **"How would an automated test verify this?"** + +| Weak Criterion | Strong Criterion | +|----------------|-----------------| +| "UI should look good" | "All interactive elements have minimum 44x44px touch targets" | +| "System should be fast" | "API responses return within 200ms at p95 under 100 concurrent users" | +| "Handle errors gracefully" | "Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)" | +| "Support authentication" | "Valid credentials return a session token; invalid credentials return 401 with error message" | + +### Acceptance Criteria Format + +Each criterion should be: +- **Observable** โ€” can be checked by reading output, UI state, or logs +- **Deterministic** โ€” same input always produces same pass/fail result +- **Automatable** โ€” an agent can write a test that checks this +- **Independent** โ€” does not depend on subjective judgment + +```markdown +**Acceptance Criteria:** +- [ ] {Action} results in {observable outcome} +- [ ] Given {precondition}, when {action}, then {result} +- [ ] {Metric} meets {threshold} under {conditions} +``` + +--- + +## Hierarchical Structure with Index + +Blueprints must be organized as a hierarchy โ€” one index file linking to domain-specific sub-blueprints. This enables progressive disclosure: agents read the index first, then only the sub-blueprints relevant to their task. + +### The Blueprint Index Pattern + +Create a `blueprint-overview.md` as the entry point: + +```markdown +# Blueprint Overview + +## Domains + +| Domain | Blueprint File | Summary | +|--------|-----------|---------| +| Authentication | blueprint-auth.md | User registration, login, session management, OAuth | +| Data Models | blueprint-data-models.md | Core entities, relationships, validation rules | +| API | blueprint-api.md | REST endpoints, request/response formats, error handling | +| UI Components | blueprint-ui-components.md | Shared components, accessibility, responsive behavior | +| Notifications | blueprint-notifications.md | Email, push, in-app notification delivery | + +## Cross-Cutting Concerns +- Security requirements: see blueprint-auth.md R3, blueprint-api.md R7 +- Performance budgets: see blueprint-api.md R12, blueprint-ui-components.md R5 +- Accessibility: see blueprint-ui-components.md R8-R10 +``` + +### Why Hierarchical? + +1. **Context window efficiency** โ€” agents load only the domains they need +2. **Parallel work** โ€” different agents can own different spec domains +3. **Review efficiency** โ€” humans can review domain-by-domain +4. **Cross-referencing** โ€” domains link to each other explicitly + +--- + +## Cross-Referencing Between Blueprints + +Related blueprints must link to each other. Cross-references prevent requirements from being lost at domain boundaries. + +### Cross-Reference Patterns + +```markdown +## Cross-References +- **Depends on:** blueprint-auth.md R1 (session tokens required for API access) +- **Depended on by:** blueprint-notifications.md R4 (uses user preferences from this blueprint) +- **Related:** blueprint-ui-components.md R6 (error display components used by this domain) +``` + +### When to Cross-Reference + +- When one domain's requirement depends on another domain's output +- When shared entities are defined in one blueprint but used in many +- When validation criteria span multiple domains +- When out-of-scope items are in-scope for another blueprint + +--- + +## Full Blueprint Format Template + +Use this template for every domain blueprint: + +```markdown +# Blueprint: {Domain Name} + +## Scope +{One paragraph describing what this spec covers and its boundaries.} + +## Requirements + +### R1: {Requirement Name} +**Description:** {What must be true โ€” stated in terms of behavior, not implementation.} +**Acceptance Criteria:** +- [ ] {Testable criterion 1} +- [ ] {Testable criterion 2} +- [ ] {Testable criterion 3} +**Dependencies:** {Other specs/requirements this depends on, or "None"} + +### R2: {Requirement Name} +**Description:** {What must be true} +**Acceptance Criteria:** +- [ ] {Testable criterion 1} +- [ ] {Testable criterion 2} +**Dependencies:** {Dependencies} + +### R3: ... + +## Out of Scope +{Explicit list of things this blueprint does NOT cover. This is critical โ€” it prevents +agents from over-building and clarifies domain boundaries.} +- {Thing explicitly excluded and why} +- {Another exclusion} + +## Cross-References +- See also: blueprint-{related-domain}.md โ€” {why it is related} +- Depends on: blueprint-{dependency}.md R{N} โ€” {what is needed} +- Depended on by: blueprint-{dependent}.md R{N} โ€” {what depends on this} +``` + +### Template Rules + +1. **Number requirements sequentially** (R1, R2, R3...) โ€” agents reference them by ID +2. **Every requirement gets acceptance criteria** โ€” no exceptions +3. **Out of Scope is mandatory** โ€” explicit exclusions prevent scope creep +4. **Cross-References section is mandatory** โ€” even if it says "None" +5. **Scope section is one paragraph** โ€” concise boundary description + +--- + +## Greenfield Pattern: Reference Material โ†’ Blueprints + +When building from scratch, you start with reference materials and derive blueprints from them. + +### Flow + +``` +context/refs/ context/blueprints/ +โ”œโ”€โ”€ prd.md โ†’ โ”œโ”€โ”€ blueprint-overview.md +โ”œโ”€โ”€ design-doc.md โ†’ โ”œโ”€โ”€ blueprint-auth.md +โ”œโ”€โ”€ api-draft.md โ†’ โ”œโ”€โ”€ blueprint-api.md +โ””โ”€โ”€ research/ โ†’ โ”œโ”€โ”€ blueprint-data-models.md + โ””โ”€โ”€ ... โ†’ โ””โ”€โ”€ blueprint-ui.md +``` + +### Process + +1. **Place all reference materials** in `context/refs/` +2. **Run blueprint generation** โ€” agent reads all refs, decomposes into domains +3. **Agent produces:** + - `blueprint-overview.md` โ€” index with domain summaries + - One `blueprint-{domain}.md` per identified domain + - Cross-references between related domains +4. **Human reviews** blueprints for completeness and correctness +5. **Iterate** โ€” refine blueprints based on review feedback + +### Greenfield Prompt Pattern + +The first prompt in a greenfield pipeline (typically `001-generate-blueprints-from-refs.md`) should: +- Read all files in `context/refs/` +- Decompose reference material into domains +- Generate blueprints following the template above +- Create `blueprint-overview.md` as the index +- Cross-reference related blueprints + +--- + +## Rewrite Pattern: Old Code โ†’ Reference Docs โ†’ Blueprints + +When rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code โ€” you always extract blueprints first. + +### Flow + +``` +Existing codebase context/refs/ context/blueprints/ +โ”œโ”€โ”€ src/ โ†’ โ”œโ”€โ”€ ref-apis.md โ†’ โ”œโ”€โ”€ blueprint-overview.md +โ”œโ”€โ”€ tests/ โ†’ โ”œโ”€โ”€ ref-data-models.md โ†’ โ”œโ”€โ”€ blueprint-auth.md +โ””โ”€โ”€ docs/ โ†’ โ”œโ”€โ”€ ref-ui-components.md โ†’ โ”œโ”€โ”€ blueprint-api.md + โ””โ”€โ”€ ref-architecture.md โ†’ โ””โ”€โ”€ blueprint-data.md +``` + +### Process + +1. **Agent explores the existing codebase** and generates reference documents +2. **Reference docs capture** the current system's behavior, APIs, data models, and UI patterns +3. **Agent generates blueprints** from reference docs โ€” implementation-agnostic requirements +4. **Validate blueprints against existing code** โ€” verify acceptance criteria match current behavior +5. **Proceed with normal DABI** โ€” blueprints drive the new implementation + +### Rewrite Prompt Pattern + +Rewrites typically use more prompts because of the reverse-engineering step: +- `001`: Generate reference materials from old code +- `002`: Generate blueprints from references + feature scope +- `003`: Validate blueprints against existing codebase +- `004+`: Plans and implementation + +The key difference from greenfield: step 003 validates that your blueprints actually describe what the old system does, before you start building the new one. + +--- + +## Blueprint Compaction + +When implementation tracking or blueprint files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context. + +### When to Compact + +- Implementation tracking file exceeds 500 lines +- Blueprint file has many resolved/completed requirements mixed with active ones +- Agent is spending too much context window on historical information + +### How to Compact + +1. **Identify resolved content:** completed tasks, resolved issues, archived dead ends +2. **Archive removed content** to a separate file (e.g., `impl/archive/impl-domain-v1.md`) +3. **Preserve in the compacted file:** + - All active/in-progress tasks + - All open issues + - Recent dead ends (last 2-3 sessions) + - Current test health status + - Active cross-references +4. **Target:** under 500 lines in the active file + +### Compaction Rule + +Never delete information โ€” move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations. + +--- + +## Gap Analysis + +Gap analysis compares what was built against what was intended, identifying where blueprints, plans, or validation fell short. + +### How to Perform Gap Analysis + +1. **Read blueprints** (intended behavior) and **implementation tracking** (what was built) +2. **For each blueprint requirement,** check if acceptance criteria are satisfied +3. **Classify each requirement:** + +| Status | Meaning | +|--------|---------| +| **Complete** | All acceptance criteria pass | +| **Partial** | Some criteria pass, others do not | +| **Missing** | Requirement not implemented at all | +| **Over-built** | Implementation exceeds blueprint (may indicate blueprint gap) | + +4. **Report gaps** with: which blueprint, which criterion, what is missing +5. **Feed gaps into revision** โ€” update blueprints if needed, then re-implement + +### Gap Analysis as Feedback + +Gap analysis is not a one-time activity. Run it: +- After each implementation iteration +- Before starting a new session (to prioritize work) +- When convergence stalls (to identify what is blocking progress) + +--- + +## Integration with Other Skills + +### Collaborative Design in the Draft Phase + +The Draft phase (`/bp:draft`) now embeds brainstorming principles directly. When running in interactive mode (no arguments), the drafter follows a collaborative design process before generating any files: + +1. **Explore project context** โ€” check existing files, docs, commits before asking questions +2. **Ask clarifying questions one at a time** โ€” understand purpose, constraints, success criteria +3. **Propose 2-3 domain decomposition approaches** โ€” with tradeoffs and a recommendation +4. **Present the design incrementally** โ€” section by section, get approval per domain +5. **Generate blueprints only after design approval** โ€” formalize with acceptance criteria +6. **Blueprint review loop** โ€” automated reviewer checks quality, up to 3 iterations +7. **User review gate** โ€” explicit approval before transitioning to Architect phase + +This process applies to EVERY project regardless of perceived simplicity. The design can be short for simple projects, but it must happen. + +**Visual companion:** For projects involving visual elements (UI, architecture diagrams), the Draft phase can use a browser-based visual companion to show mockups and diagrams during the design conversation. See `references/visual-companion.md`. + +**YAGNI enforcement:** During the design conversation and blueprint generation, actively strip requirements the user did not ask for. Smaller blueprints are better blueprints. + +### With `bp:design-system` + +When DESIGN.md exists at the project root, blueprints for UI domains should reference design tokens in acceptance criteria. This creates a traceable chain: DESIGN.md -> blueprint acceptance criterion -> plan task -> implementation. + +| Acceptance Criterion Type | Design Reference | +|--------------------------|-----------------| +| "Button has primary CTA appearance" | DESIGN.md Section 4, primary button variant | +| "Text follows heading hierarchy" | DESIGN.md Section 3, type scale | +| "Card has subtle elevation" | DESIGN.md Section 6, elevation level 1 | +| "Layout uses 12-column grid" | DESIGN.md Section 5, grid system | +| "Colors adapt for dark mode" | DESIGN.md Section 2, dark mode mapping | + +**Do NOT duplicate DESIGN.md content into blueprints.** Reference by section/token name only. If a color changes in DESIGN.md, blueprints should not need updating. + +When a blueprint needs a visual pattern not yet defined in DESIGN.md, note it in the acceptance criterion: +```markdown +- [ ] Component uses card-like container [DESIGN.md: pattern not yet defined โ€” flag for design update] +``` + +### With `bp:validation-first` + +Every acceptance criterion in a blueprint must map to at least one validation gate. When writing blueprints, think about which gate will verify each requirement: + +| Acceptance Criterion Type | Likely Gate | +|--------------------------|-------------| +| "Code compiles without errors" | Gate 1: Build | +| "Function returns correct output for input X" | Gate 2: Unit Tests | +| "User can complete workflow end-to-end" | Gate 3: E2E/Integration | +| "Response time under N ms" | Gate 4: Performance | +| "Application starts and displays main screen" | Gate 5: Launch Verification | +| "UI matches design intent" | Gate 6: Human Review | + +### With `bp:context-architecture` + +Blueprints live in the `context/blueprints/` directory. See `bp:context-architecture` for the full context directory structure, CLAUDE.md conventions, and multi-repo strategies. + +### With `bp:impl-tracking` + +As blueprints are implemented, progress is tracked in `context/impl/` documents. Dead ends discovered during implementation should be recorded to prevent future agents from retrying failed approaches. + +--- + +## Common Mistakes + +### 1. Writing Implementation-Specific Blueprints + +**Wrong:** "Use PostgreSQL with a users table containing columns: id (UUID), email (VARCHAR), ..." +**Right:** "User accounts have a unique identifier and email. Email must be unique across all accounts. Acceptance: creating two accounts with the same email fails with a duplicate error." + +### 2. Vague Acceptance Criteria + +**Wrong:** "System handles errors properly" +**Right:** "When a network request fails, the UI displays an error message within 2 seconds and offers a retry action. Acceptance: simulating network failure shows error banner with retry button." + +### 3. Missing Out of Scope + +Every blueprint needs explicit exclusions. Without them, agents will over-build or make assumptions. + +### 4. No Cross-References + +Domains do not exist in isolation. If blueprint-auth defines session tokens that blueprint-api uses, both blueprints must cross-reference each other. + +### 5. Monolithic Blueprints + +A single 1000-line blueprint file defeats progressive disclosure. Decompose into domains with a clear index. + +--- + +## Summary + +Writing blueprints for AI agents follows these rules: + +1. **WHAT, not HOW** โ€” describe behavior, not implementation +2. **Every requirement gets testable acceptance criteria** โ€” if agents cannot validate it, it will not be met +3. **Hierarchical with an index** โ€” progressive disclosure for context efficiency +4. **Cross-referenced** โ€” related domains link to each other +5. **Explicitly scoped** โ€” out-of-scope section prevents over-building +6. **Compact when large** โ€” archive resolved content, keep active files under 500 lines +7. **Living documents** โ€” blueprints evolve through revision as gaps are discovered diff --git a/plugins/JuliusBrussee/blueprint/skills/brownfield-adoption/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/brownfield-adoption/SKILL.md new file mode 100644 index 0000000..c9a7072 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/brownfield-adoption/SKILL.md @@ -0,0 +1,469 @@ +--- +name: brownfield-adoption +description: > + Step-by-step process for adopting Blueprint on an existing codebase. + Covers the 6-step brownfield process, bootstrap prompt design, spec validation against + existing behavior, and the decision between brownfield adoption vs deliberate rewrite. + Trigger phrases: "brownfield", "existing codebase", "add Blueprint to existing project", + "adopt Blueprint", "layer blueprints on code", "retrofit blueprints" +--- + +# Brownfield Adoption: Adding Blueprint to Existing Codebases + +Brownfield adoption layers blueprints on top of existing code without rewriting it. The existing codebase becomes reference material, and blueprints are reverse-engineered from what the code actually does. Once blueprints exist, all future changes flow through the Blueprint lifecycle. + +**Core principle:** The existing code is not the enemy -- it is the source of truth for blueprint generation. Respect what works; blueprint what matters. + +--- + +## 1. When to Use Brownfield Adoption + +Brownfield adoption is the right choice when: + +- You have a **working codebase** that you want to improve incrementally +- You want to adopt Blueprint **without stopping development** +- The codebase is too large or critical for a full rewrite +- You want **traceability** between blueprints and code for future changes +- You need to **onboard AI agents** to an existing project safely +- The team wants to start with Blueprint on a subset of the codebase + +**Brownfield is NOT the right choice when:** +- You are migrating to a completely different framework (use a deliberate rewrite instead) +- The existing code is so broken that blueprints would just document bugs +- The codebase is being sunset or replaced + +--- + +## 2. Brownfield vs Deliberate Rewrite + +Before starting, decide which approach fits your situation: + +| Dimension | Incremental Adoption | Clean-Slate Rebuild | +|-----------|---------------------|---------------------| +| **Objective** | Add blueprint coverage around working code | Replace the codebase with a new implementation | +| **What happens to existing code** | Remains in place, evolves under Blueprint governance | Archived once blueprints are extracted; new code replaces it | +| **Risk profile** | Lower -- production system stays functional throughout | Higher -- new system must achieve feature parity before cutover | +| **Time to first value** | Fast -- blueprints appear in days, improvements follow | Slow -- significant upfront investment before any return | +| **Ideal scenarios** | Production systems, incremental improvement, large legacy codebases | Technology stack changes, irrecoverable tech debt, greenfield-quality rebuilds | +| **How blueprints originate** | Derived by analyzing existing behavior | Written forward from product requirements | +| **Handling broken behavior** | Blueprints capture current state; bugs are fixed through normal Blueprint cycles | Blueprints capture intended state; fresh implementation avoids old bugs | +| **Impact on ongoing work** | Low -- regular development continues alongside adoption | High -- team capacity is split between old and new systems | + +### Decision flowchart + +``` +Is the existing code fundamentally sound? + YES -> Are you changing frameworks? + YES -> Deliberate Rewrite (extract specs, build new) + NO -> Brownfield Adoption (layer specs, evolve) + NO -> Is a rewrite feasible (time, budget, risk)? + YES -> Deliberate Rewrite + NO -> Brownfield Adoption (spec the broken parts, fix incrementally) +``` + +--- + +## 3. The 6-Step Brownfield Process + +### Step 1: Set Up the Context Directory + +Create the standard Blueprint context directory structure alongside your existing codebase: + +```bash +mkdir -p context/{refs,blueprints,plans,impl,prompts} +``` + +Resulting structure: + +``` +your-project/ ++-- src/ # Existing source code (untouched) ++-- tests/ # Existing tests (untouched) ++-- package.json # Existing config (untouched) ++-- context/ + +-- refs/ + | +-- architecture-overview.md # High-level description of existing system + +-- blueprints/ + | +-- CLAUDE.md # "Blueprints define WHAT needs implementing" + +-- plans/ + | +-- CLAUDE.md # "Plans define HOW to implement something" + +-- impl/ + | +-- CLAUDE.md # "Impls record implementation progress" + +-- prompts/ + +-- 000-generate-blueprints-from-code.md # Bootstrap prompt (this step) +``` + +**Create `context/refs/architecture-overview.md`** with a high-level description of the existing system: + +```markdown +# Architecture Overview + +## System Description +{Brief description of what the application does} + +## Technology Stack +- Language: {LANGUAGE} +- Framework: {FRAMEWORK} +- Build: {BUILD_COMMAND} +- Test: {TEST_COMMAND} + +## Directory Structure +{Key directories and their purposes} + +## Key Domains +{List the major functional areas of the application} + +## External Dependencies +{APIs, databases, services the application depends on} + +## Known Issues / Tech Debt +{Major known issues that specs should account for} +``` + +### Step 2: Designate the Codebase as Reference Material + +The existing codebase itself becomes the reference material. Unlike greenfield projects (where refs are PRDs or language specs), brownfield refs are the living code. + +**In `context/refs/`, add a pointer:** + +```markdown +# Reference: Existing Codebase + +The existing source code at `src/` is the primary reference material for spec generation. + +## How to Use This Reference +1. Explore the codebase structure to identify domains +2. Read source files to understand current behavior +3. Run existing tests to understand expected behavior +4. Check git history for context on design decisions + +## What the Codebase Tells Us +- Current behavior (what the code DOES) +- Implicit requirements (what the code assumes) +- Test coverage (what is validated) +- Architecture decisions (how domains interact) + +## What the Codebase Does NOT Tell Us +- Why decisions were made (check git history, docs) +- What behavior is intentional vs accidental +- What requirements are missing +- What the system SHOULD do vs what it DOES +``` + +### Step 3: Create the Bootstrap Prompt (000) + +The bootstrap prompt is numbered `000` because it runs first and only once. It reverse-engineers blueprints from the existing code. + +```markdown +# 000: Generate Blueprints from Existing Code (Brownfield Bootstrap) + +## Runtime Inputs +- Framework: {FRAMEWORK} +- Build command: {BUILD_COMMAND} +- Test command: {TEST_COMMAND} +- Source directory: {SRC_DIR} + +## Context +This is a brownfield adoption. The existing codebase at `{SRC_DIR}` is the reference material. +Read `context/refs/architecture-overview.md` for system context. + +## Task + +### Phase 1: Explore and Discover +1. Read the architecture overview +2. Explore the source directory structure +3. Identify distinct functional domains (auth, data, UI, API, etc.) +4. Read key source files in each domain +5. Run existing tests to understand expected behavior: `{TEST_COMMAND}` + +### Phase 2: Generate Blueprints +For each identified domain: +1. Create `context/blueprints/blueprint-{domain}.md` +2. Each blueprint must include: + - **Scope:** What this domain covers + - **Requirements:** What the code currently does, expressed as requirements + - **Acceptance Criteria:** Testable criteria derived from existing behavior + - **Dependencies:** What other domains this depends on + - **Out of Scope:** What this blueprint explicitly excludes + - **Cross-References:** Links to related blueprints + +3. Create `context/blueprints/blueprint-overview.md` as the index: + - One-line summary per domain blueprint + - Dependency graph between domains + - Overall system architecture summary + +### Phase 3: Validate +For each acceptance criterion in the generated blueprints: +1. Verify the existing code satisfies it +2. If a test exists that validates it, reference the test +3. If no test exists, note it as a coverage gap + +## Exit Criteria +- [ ] All major domains have corresponding blueprint files +- [ ] Every requirement has testable acceptance criteria +- [ ] blueprint-overview.md indexes all blueprints +- [ ] Validation report shows which criteria are covered by existing tests +- [ ] Coverage gaps are documented + +## Completion Signal + +``` + +### Step 4: Run the Iteration Loop + +Run the bootstrap prompt through the iteration loop: + +```bash +# Run 3-5 iterations to stabilize blueprints +iteration-loop context/prompts/000-generate-blueprints-from-code.md -n 5 -t 1h +``` + +**What happens during iteration:** +- **Iteration 1:** Agent explores codebase, generates initial blueprints (broad but shallow) +- **Iteration 2:** Agent refines blueprints based on git history from iteration 1, adds detail +- **Iteration 3:** Agent validates blueprints against code, fills coverage gaps +- **Iterations 4-5:** Convergence -- minor refinements, polishing cross-references + +**Watch for convergence:** Blueprints should stabilize after 3-5 iterations. If they do not, the codebase may be too large for a single prompt. Split into domain-specific bootstrap prompts. + +### Step 5: Validate Blueprints Match Behavior + +After the bootstrap prompt converges, validate that the generated blueprints accurately describe the existing code: + +#### 5a. Run tests against blueprints + +```bash +# Use TDD to verify blueprints match behavior +# For each domain blueprint, generate tests from acceptance criteria +# then verify existing code passes them +{TEST_COMMAND} +``` + +#### 5b. Manual review checklist + +```markdown +## Blueprint Validation Checklist +- [ ] Each domain in the codebase has a corresponding blueprint +- [ ] Acceptance criteria match actual code behavior (not aspirational) +- [ ] Dependencies between blueprints match actual code dependencies +- [ ] No orphan code -- every significant module is covered by a blueprint +- [ ] No phantom requirements -- blueprints do not describe behavior that does not exist +- [ ] Cross-references are accurate +``` + +#### 5c. Handle mismatches + +| Mismatch Type | Action | +|--------------|--------| +| **Blueprint describes behavior that does not exist** | Remove the requirement (phantom requirement) | +| **Code has behavior not in any blueprint** | Add a requirement (coverage gap) | +| **Blueprint and code disagree on behavior** | Determine which is correct; update the other | +| **Code has bugs that blueprints documented as-is** | Mark as known issue in blueprint; fix via normal Blueprint | + +### Step 6: Proceed with Normal DABI + +Once blueprints are validated, the project is ready for full Blueprint. All future changes flow through blueprints first: + +``` +Future change workflow: + 1. Update blueprint with new/changed requirement + 2. Generate/update plans from blueprints (prompt 002) + 3. Implement from plans (prompt 003) + 4. Validate: build + test + acceptance criteria + 5. If issues found: revise blueprints +``` + +Create the standard pipeline prompts: + +```bash +# Create greenfield-style prompts for ongoing development +# (000 was the bootstrap; 001-003 are the ongoing pipeline) +context/prompts/001-generate-blueprints-from-refs.md # For new features +context/prompts/002-generate-plans-from-blueprints.md # Plan generation +context/prompts/003-generate-impl-from-plans.md # Implementation +``` + +--- + +## 4. Incremental Adoption Strategy + +You do not have to blueprint the entire codebase at once. Start with the most active or highest-risk areas: + +### Priority matrix for blueprint coverage + +| Priority | Criteria | Example | +|----------|----------|---------| +| **P0: Blueprint immediately** | Code changes frequently, high risk, many bugs | Auth system, payment processing | +| **P1: Blueprint soon** | Active development area, moderate complexity | Feature modules, API endpoints | +| **P2: Blueprint when touched** | Stable code, rarely changes | Utility libraries, config modules | +| **P3: Skip until needed** | Dead code, deprecated features | Legacy compatibility layers | + +### Incremental process + +``` +Week 1: Bootstrap blueprints for P0 domains + -> Run 000 prompt scoped to P0 directories only + -> Validate and refine + +Week 2-3: Extend to P1 domains + -> Add P1 directories to the bootstrap prompt + -> Cross-reference with existing P0 blueprints + +Week 4+: Blueprint-on-touch + -> When any P2 file is modified, generate its blueprint first + -> Gradually expand coverage +``` + +### Scoping the bootstrap prompt + +For incremental adoption, modify prompt 000 to target specific directories: + +```markdown +## Scope +This bootstrap targets the following domains only: +- `src/auth/` -> blueprint-auth.md +- `src/payments/` -> blueprint-payments.md + +Do NOT generate blueprints for other directories at this time. +``` + +--- + +## 5. Common Challenges and Solutions + +### Challenge: Codebase is too large for one context window + +**Solution:** Split the bootstrap into domain-specific prompts: + +``` +context/prompts/ ++-- 000a-generate-blueprints-auth.md ++-- 000b-generate-blueprints-data.md ++-- 000c-generate-blueprints-ui.md +``` + +Run each independently, then create a manual `blueprint-overview.md` that ties them together. + +### Challenge: No existing tests + +**Solution:** The bootstrap prompt generates blueprints from code behavior, not tests. After blueprints exist, use the implementation prompt to generate tests: + +```bash +# After bootstrap, generate tests from blueprints +iteration-loop context/prompts/003-generate-impl-from-plans.md -n 5 -t 1h +# Focus on test generation, not code changes +``` + +### Challenge: Code has undocumented behavior + +**Solution:** Use git history to understand intent: + +```markdown +# In the bootstrap prompt, add: + +## Discovery Strategy +1. Read source code for current behavior +2. Read `git log --oneline -50` for recent changes +3. Read `git log --follow {file}` for individual file history +4. Infer requirements from both code AND history +``` + +### Challenge: Code has known bugs + +**Solution:** Blueprint the intended behavior, not the buggy behavior. Mark known bugs as issues: + +```markdown +### R3: Search Results Pagination +**Description:** Search results are paginated with 20 items per page +**Acceptance Criteria:** +- [ ] Results are paginated +- [ ] Page size is configurable (default 20) +**Known Issues:** +- BUG: Off-by-one error on last page (see issue #142) +``` + +### Challenge: Team resistance to Blueprint + +**Solution:** Start small, show results: +1. Pick ONE upcoming feature +2. Write a blueprint before implementing it +3. Show how the blueprint caught issues the team would have missed +4. Gradually expand Blueprint coverage based on demonstrated value + +--- + +## 6. Lightweight Blueprint for Small Projects + +Even small projects benefit from minimal Blueprint. The "Blueprint floor" is: + +``` +your-small-project/ ++-- src/ ++-- context/ + +-- blueprints/ + | +-- blueprint-task.md # One blueprint for the current task + +-- plans/ + +-- plan-task.md # One plan for the current task +``` + +**No prompts directory needed.** Just write a focused blueprint and plan, then use the iteration loop against the plan. + +**Why bother for small projects?** +- The blueprint catches requirements you would have missed +- The plan sequences work so the agent does not thrash +- If the project grows, you already have the structure in place +- It is much easier to scale up from lightweight Blueprint than to retrofit full Blueprint later + +### Lightweight Blueprint process + +1. Write `context/blueprints/blueprint-task.md` (15-30 minutes) +2. Write `context/plans/plan-task.md` (10-20 minutes) +3. Run the iteration loop against the plan +4. If the project grows, add the full context directory structure + +--- + +## 7. Transition Milestones + +Track your brownfield adoption progress with these milestones: + +```markdown +## Brownfield Adoption Progress + +### Milestone 1: Foundation +- [ ] Context directory created +- [ ] Architecture overview written +- [ ] Bootstrap prompt created + +### Milestone 2: Initial Specs +- [ ] P0 domains have blueprints +- [ ] Blueprints validated against existing code +- [ ] Coverage gaps documented + +### Milestone 3: Pipeline Active +- [ ] Standard prompts (001-003) created +- [ ] First feature developed through Blueprint pipeline +- [ ] Revision process tested + +### Milestone 4: Steady State +- [ ] All active domains have blueprints +- [ ] All new features go through blueprints first +- [ ] Revision is routine +- [ ] Iteration loop runs are predictable (convergence in 3-5 iterations) + +### Milestone 5: Full Blueprint +- [ ] All domains have blueprints +- [ ] All changes flow through DABI +- [ ] Convergence monitoring active +- [ ] Team comfortable with the process +``` + +--- + +## Cross-References + +- **Context architecture:** See `bp:context-architecture` skill for the full context directory structure and progressive disclosure patterns. +- **Prompt pipeline:** See `bp:prompt-pipeline` skill for designing the 001-003 prompts after bootstrap. +- **Blueprint writing:** See `bp:blueprint-writing` skill for how to write high-quality blueprints with testable acceptance criteria. +- **Revision:** See `bp:revision` skill for tracing bugs back to blueprints after brownfield adoption. +- **Convergence monitoring:** See `bp:convergence-monitoring` skill for detecting when the bootstrap prompt has converged. diff --git a/plugins/JuliusBrussee/blueprint/skills/context-architecture/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/context-architecture/SKILL.md new file mode 100644 index 0000000..c9b87c6 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/context-architecture/SKILL.md @@ -0,0 +1,281 @@ +--- +name: context-architecture +description: | + Progressive disclosure architecture for organizing project context as a DAG (directed acyclic graph). + Agents enter at the root and traverse only the subgraph relevant to their task. + Covers the 4-tier information flow (refs โ†’ blueprints โ†’ plans โ†’ impl), CLAUDE.md hierarchy + across context/ and source tree, index files as DAG hub nodes, nesting rules, and backward compatibility. + Trigger phrases: "context architecture", "progressive disclosure", "organize context for agents", + "context directory structure", "how to structure docs for AI", "context hierarchy" +--- + +# Context Architecture: DAG-Based Progressive Disclosure + +## Core Principle + +**Agents should only read what they need.** Documents are organized as a directed acyclic graph (DAG) where index files act as hub nodes. An agent reads the index, identifies relevant edges, and follows only those to leaf documents. No agent ever loads the full tree. + +--- + +## The 4-Tier Information Flow + +``` +refs/ (what IS) --> blueprints/ (what MUST BE) --> plans/ (HOW) --> impl/ (what WAS DONE) + Tier 1 Tier 2 Tier 3 Tier 4 +``` + +Each tier consumes the previous tier's output. Cross-references between tiers create the DAG edges that agents traverse. + +--- + +## Directory Layout + +``` +context/ +โ”œโ”€โ”€ CLAUDE.md # Root entry node: describes all tiers + design layer +โ”œโ”€โ”€ refs/ # Tier 1: Source material (read-only input) +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "Source of truth. Organized by source. Read-only." +โ”‚ โ””โ”€โ”€ {source}/ # Subdirs per source (e.g., prd/, api-spec/) +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ blueprints/ # Tier 2: WHAT to build +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "Start at blueprint-overview.md. R-numbered reqs." +โ”‚ โ”œโ”€โ”€ blueprint-overview.md # Index node (DAG hub) +โ”‚ โ”œโ”€โ”€ blueprint-{domain}.md # Leaf โ€” simple domain (single file) +โ”‚ โ””โ”€โ”€ {domain}/ # Complex domain gets a subdirectory +โ”‚ โ”œโ”€โ”€ blueprint-{domain}.md # Domain index (becomes hub node) +โ”‚ โ””โ”€โ”€ blueprint-{domain}-{sub}.md # Sub-domain leaves +โ”œโ”€โ”€ designs/ # Cross-cutting: visual design system +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "DESIGN.md at project root is canonical." +โ”‚ โ””โ”€โ”€ design-changelog.md # Append-only change log +โ”œโ”€โ”€ plans/ # Tier 3: HOW to build (task graphs) +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "Start at plan-overview.md. Task dependency tiers." +โ”‚ โ”œโ”€โ”€ plan-overview.md # Index node +โ”‚ โ”œโ”€โ”€ build-site.md # Primary build site +โ”‚ โ”œโ”€โ”€ build-site-{feature}.md # Feature-specific build sites +โ”‚ โ””โ”€โ”€ {domain}/ # Complex plans get subdirectories +โ”‚ โ””โ”€โ”€ plan-{domain}-{area}.md +โ”œโ”€โ”€ impl/ # Tier 4: What WAS DONE +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "Start at impl-overview.md. Update after every session." +โ”‚ โ”œโ”€โ”€ impl-overview.md # Index node +โ”‚ โ”œโ”€โ”€ impl-{domain}.md # Per-domain tracking +โ”‚ โ”œโ”€โ”€ impl-review-findings.md # Codex review findings ledger +โ”‚ โ”œโ”€โ”€ dead-ends.md # Failed approaches (shared across domains) +โ”‚ โ””โ”€โ”€ archive/ # Compacted/archived tracking +``` + +> **Note:** `designs/` is a **cross-cutting constraint layer**, not a fifth tier. DESIGN.md (at project root) is read by agents at every DABI phase โ€” Draft reads it to constrain visual decisions, Architect references tokens in task descriptions, Build uses it for implementation, Inspect validates against it. It parallels how CLAUDE.md files provide conventions, but for visual design. + +### Backward Compatibility: sites/ โ†’ plans/ + +Build sites previously lived in `context/sites/`. All Blueprint commands check both locations: + +1. Look in `context/plans/` +2. If not found, fall back to `context/sites/` +3. If found in `sites/`, use it โ€” no auto-migration, no breakage + +`/bp:init` offers optional migration. Declining is permanent โ€” the system works with either layout. + +--- + +## CLAUDE.md Hierarchy + +### Scope: Full Repository + +`CLAUDE.md` files extend beyond `context/` into the source code tree. They form the connective tissue between code and the context DAG. + +``` +project/ +โ”œโ”€โ”€ CLAUDE.md # Project root: build/test commands, +โ”‚ # "context/ has the full hierarchy" +โ”œโ”€โ”€ context/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md # Root context node: 4 tiers described +โ”‚ โ”œโ”€โ”€ refs/CLAUDE.md # Tier 1 conventions +โ”‚ โ”œโ”€โ”€ blueprints/CLAUDE.md # Tier 2 conventions +โ”‚ โ”œโ”€โ”€ plans/CLAUDE.md # Tier 3 conventions +โ”‚ โ””โ”€โ”€ impl/CLAUDE.md # Tier 4 conventions +โ”‚ +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md # Source code conventions +โ”‚ โ”œโ”€โ”€ auth/ +โ”‚ โ”‚ โ”œโ”€โ”€ CLAUDE.md # "implements blueprint-auth.md R1-R3" +โ”‚ โ”‚ โ””โ”€โ”€ ... +โ”‚ โ””โ”€โ”€ parser/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md # "implements blueprint-grammar.md R1-R4, +โ”‚ โ”‚ # see plans/build-site.md T-012 through T-018" +โ”‚ โ””โ”€โ”€ ... +โ”‚ +โ”œโ”€โ”€ tests/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md # Test conventions, how to run +โ”‚ โ””โ”€โ”€ ... +โ””โ”€โ”€ scripts/ + โ”œโ”€โ”€ CLAUDE.md # Utility script conventions + โ””โ”€โ”€ ... +``` + +### Loading Behavior + +When an agent works in `src/auth/`, it loads hierarchically: +1. `project/CLAUDE.md` โ€” project-level conventions +2. `project/src/CLAUDE.md` โ€” source code conventions +3. `project/src/auth/CLAUDE.md` โ€” **"implements blueprint-auth.md R1-R3"** + +The third file bridges to the context DAG. The agent knows which blueprint to load without loading the entire `context/blueprints/` directory. + +### CLAUDE.md Design Principles + +- **Minimal** โ€” 3-10 lines for source-tree files. Never duplicate blueprint content. +- **Connective** โ€” each one names the blueprint requirements and plan tasks it relates to. +- **Contextual** โ€” includes module-specific conventions (error handling patterns, test fixture locations). +- **Honest** โ€” `/bp:build` only writes mappings it is certain about (tasks it completed, files it created). + +--- + +## Progressive Disclosure: The DAG Traversal + +### How Agents Navigate + +1. **Enter at root** โ€” read `context/CLAUDE.md` to understand the 4 tiers +2. **Select tier** โ€” based on current task, navigate to the relevant tier's `CLAUDE.md` +3. **Read index** โ€” the tier's overview file is the DAG hub, listing all domains with one-line summaries +4. **Follow edges** โ€” read only the domain files relevant to the current task +5. **Cross-reference** โ€” if a domain references another, follow that edge only if needed +6. **Nest deeper** โ€” if a domain has subdirectories, its root file is the sub-index; spider from there + +### Index File Format + +Every overview file follows the same format: + +```markdown +# Blueprint Overview + +| Domain | File | Summary | Status | +|--------|------|---------|--------| +| Authentication | blueprint-auth.md | Registration, login, sessions, OAuth | DRAFT | +| Data Models | blueprint-data-models.md | Core entities, relationships, validation | DRAFT | +| Type System | blueprint-type-system.md | Effects lattice, tagged values (see type-system/) | DRAFT | +``` + +An agent reads this table, identifies "I need Authentication," and loads only `blueprint-auth.md`. + +### Cross-Reference Edges + +```markdown +**Dependencies:** blueprint-auth.md R2 (session tokens required for API auth) +**See also:** blueprint-api.md R4 (rate limiting uses auth identity) +``` + +Agents follow these only when the cross-referenced content is needed for the current task. + +--- + +## Nesting Rule + +A domain stays flat (single file) by default. When a file covers multiple independent concerns that could be understood separately, it becomes an index file pointing to a subdirectory. + +**Trigger:** Cohesion, not line count. If a file has sections that an agent working on one section would never need to read the others, decompose it. + +**Example:** `blueprint-type-system.md` covers effects lattice, tagged values, and inference rules: + +``` +blueprints/ +โ”œโ”€โ”€ blueprint-type-system.md # Now an index +โ””โ”€โ”€ type-system/ + โ”œโ”€โ”€ blueprint-type-system-effects.md + โ”œโ”€โ”€ blueprint-type-system-tagged.md + โ””โ”€โ”€ blueprint-type-system-inference.md +``` + +The original file stays in place as the index โ€” no reference breakage. + +--- + +## Backpropagation via CLAUDE.md + +When a bug is found, source-tree CLAUDE.md files provide the reverse traversal: + +``` +Bug in src/auth/login.ts + | + v +src/auth/CLAUDE.md says "implements blueprint-auth.md R2" + | + v +blueprint-auth.md R2 โ€” check acceptance criteria + | + |-- Criteria missing? --> update blueprint (spec gap) + |-- Criteria wrong? --> fix blueprint (spec bug) + |-- Criteria present but code violates? --> fix code (impl bug) + | + v +If blueprint changed --> propagate to plans/ --> flag affected tasks +``` + +### Forward Propagation + +When a blueprint changes via `/bp:revise`: +1. Scan all `src/*/CLAUDE.md` files for references to the changed requirement +2. Flag those modules as potentially affected +3. New requirements with no source-tree CLAUDE.md references are unimplemented + +--- + +## Bootstrapping + +Run `/bp:init` to create the full hierarchy. It: +1. Scans existing project structure +2. Creates context directories (refs/, blueprints/, plans/, impl/) +3. Creates CLAUDE.md files using standard templates +4. Creates empty index files (blueprint-overview.md, plan-overview.md, impl-overview.md) +5. Offers migration if legacy `context/sites/` exists + +Properties: idempotent, non-destructive, no questions asked. + +--- + +## Build-Time Updates + +After `/bp:build` completes, source-tree CLAUDE.md files are generated/updated: +- New source directories get a CLAUDE.md with blueprint/plan references +- Existing CLAUDE.md files get new references appended (never removed) +- `impl-overview.md` and `plan-overview.md` are updated with current status + +--- + +## Multi-Repo Strategy + +For shared blueprints across implementations, use git submodules: + +``` +Tier 1-2 (shared): shared-context/ (submodule) + โ””โ”€โ”€ refs/ + blueprints/ + +Tier 3-4 (per-repo): context/ + โ””โ”€โ”€ plans/ + impl/ +``` + +Each framework repo includes the shared context as a submodule. Updates propagate via `git submodule update`. + +--- + +## Integration with Other Skills + +| Skill | Integration | +|-------|------------| +| `bp:blueprint-writing` | Blueprints go in `context/blueprints/` following naming conventions | +| `bp:design-system` | DESIGN.md lives at project root; `context/designs/` has CLAUDE.md and changelog | +| `bp:impl-tracking` | Tracking lives in `context/impl/`, compacted when exceeding ~500 lines | +| `bp:validation-first` | Validation results recorded in impl tracking within the hierarchy | +| `bp:revision` | `/bp:revise` traverses CLAUDE.md edges in reverse to trace bugs to specs | +| `bp:methodology` | Context structure established during Draft phase, maintained throughout DABI | + +--- + +## Anti-Patterns + +| Anti-Pattern | Why It's Wrong | Fix | +|-------------|---------------|-----| +| Flat file dump | No progressive disclosure, agents load everything | Use standard directory structure with indexes | +| Missing CLAUDE.md files | No convention guidance, no DAG edges | Run `/bp:init` or add manually | +| Monolithic documents | Defeats progressive disclosure | Decompose into domains with overview indexes | +| Stale archives in active dirs | Wastes context window | Move to `impl/archive/` | +| Duplicating blueprint content in CLAUDE.md | Content drifts, double maintenance | CLAUDE.md files only contain references | diff --git a/plugins/JuliusBrussee/blueprint/skills/convergence-monitoring/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/convergence-monitoring/SKILL.md new file mode 100644 index 0000000..16e15d5 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/convergence-monitoring/SKILL.md @@ -0,0 +1,413 @@ +--- +name: convergence-monitoring +description: > + Detecting whether agent iterations are converging toward a stable solution or hitting a ceiling. + Covers convergence signals, ceiling detection, non-convergence diagnosis, test pass rate as + a convergence metric, and forward progress tracking for large projects. + Trigger phrases: "convergence", "is the agent converging", "ceiling detection", + "when to stop iterating", "diminishing returns" +--- + +# Convergence Monitoring + +Convergence monitoring answers the most important question in iterative AI development: **when should you stop iterating?** The answer is not a fixed number of iterations or a time limit -- it is convergence. Convergence means the agent's output is stabilizing; each iteration produces fewer and smaller changes than the last. + +**Core insight:** You don't need a zero-diff -- you need the remaining modifications to be inconsequential. + +--- + +## 1. What Is Convergence? + +Convergence appears as a rapid, consistent decline in the volume of changes from one iteration to the next: + +``` +Iteration 1: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 300 lines changed +Iteration 2: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 120 lines changed +Iteration 3: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 40 lines changed +Iteration 4: โ–ˆโ–ˆ 10 lines changed (cosmetic only) + ^--- Convergence reached: the diff shrinks each pass until only cosmetic changes remain +``` + +### Convergence indicators + +| Signal | What It Means | +|--------|---------------| +| **Lines changed decreasing exponentially** | Each iteration makes roughly half the changes of the previous one | +| **Changes become trivial** | Remaining changes are formatting, comments, imports -- not behavior | +| **Tests stabilize** | Test count stops increasing; pass rate approaches 100% | +| **No new files created** | The architecture has settled; only existing files are modified | +| **Impl tracking updates shrink** | Implementation tracking changes are status updates, not new findings | +| **Completion signal emitted** | Agent determines all exit criteria are met | + +### What convergence looks like in git + +```bash +# Check lines changed per iteration +git log --oneline --stat + +# Iteration 5: trivial changes +abc1234 Iteration 5: formatting and comment fixes + 3 files changed, 8 insertions(+), 6 deletions(-) + +# Iteration 4: minor adjustments +def5678 Iteration 4: edge case handling + 5 files changed, 22 insertions(+), 8 deletions(-) + +# Iteration 3: moderate changes +ghi9012 Iteration 3: complete API integration + 12 files changed, 85 insertions(+), 31 deletions(-) + +# Iteration 2: significant changes +jkl3456 Iteration 2: implement core features + 18 files changed, 156 insertions(+), 42 deletions(-) + +# Iteration 1: major initial work +mno7890 Iteration 1: initial implementation + 25 files changed, 312 insertions(+), 15 deletions(-) +``` + +--- + +## 2. What Is a Ceiling? + +A ceiling is when the agent **cannot make further progress** due to external constraints. Like convergence, it produces small diffs -- but for fundamentally different reasons. + +``` +Convergence: Agent is DONE -> small diffs because work is complete +Ceiling: Agent is STUCK -> small diffs because agent cannot proceed +``` + +### Ceiling causes + +| Cause | Example | How to Detect | +|-------|---------|---------------| +| **Missing dependency** | API not available, library not installed | Agent logs errors about unavailable resources | +| **Ambiguous spec** | Requirement can be interpreted multiple ways | Agent oscillates between implementations | +| **Tooling limitation** | Build tool does not support needed feature | Agent tries workarounds that do not converge | +| **External service** | Test requires network access, external API | Tests fail with connection/timeout errors | +| **Context window exhaustion** | Codebase too large for one session | Agent loses track of earlier work | +| **Permission boundary** | Agent cannot access needed files or systems | Repeated permission errors in logs | + +### How to tell them apart + +| Dimension | Convergence (work is finishing) | Ceiling (work is stuck) | +|-----------|--------------------------------|-------------------------| +| **Size of diffs** | Shrinking steadily toward zero | Staying small but not trending down | +| **Nature of changes** | Cosmetic -- whitespace, comments, naming | Functional but going in circles | +| **Test results** | Pass rate climbing toward full coverage | Pass rate plateaued below target | +| **Agent stance** | Wrapping up, marking exit criteria done | Retrying the same strategies repeatedly | +| **Tracking status** | Tasks moving to DONE | BLOCKED items piling up | +| **Recommended action** | Declare done, move to next phase | Diagnose the obstacle, resolve it, then continue | + +### How to distinguish them + +``` +Check 1: Are tests passing? + YES, and improving -> Convergence + NO, stuck at same failures -> Ceiling + +Check 2: Is the agent trying new approaches? + NO, just polishing -> Convergence + YES, but they all fail similarly -> Ceiling + +Check 3: Are there BLOCKED tasks in impl tracking? + NO -> Convergence + YES -> Ceiling (read the blockers) + +Check 4: Is the agent producing meaningful error messages? + NO, just minor changes -> Convergence + YES, about dependencies/tools/access -> Ceiling +``` + +--- + +## 3. Non-Convergence Signals + +Non-convergence means the agent is making changes, but they are NOT decreasing. The system is not stabilizing. + +``` +Non-convergence: +Iteration 1: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 250 lines changed +Iteration 2: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 230 lines changed +Iteration 3: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 260 lines changed +Iteration 4: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 220 lines changed + ^--- NOT converging: changes are flat/oscillating +``` + +### Root causes of non-convergence + +| Root Cause | Symptom | Fix | +|-----------|---------|-----| +| **Fuzzy specs** | Agent interprets requirements differently each iteration | Make specs more precise; add concrete acceptance criteria | +| **Weak validation** | Agent cannot verify correctness, so it keeps changing things | Add build/test/lint gates; strengthen acceptance criteria | +| **Fighting sub-agents** | Multiple agents change the same code in conflicting ways | Add file ownership tables; dispatch subagents with `isolation: "worktree"` via the Agent tool | +| **Contradictory requirements** | Spec A says X, spec B says not-X | Resolve contradictions in specs; add explicit priority/precedence | +| **Missing exit criteria** | Agent does not know when it is done | Add explicit exit criteria checklists and completion signals | +| **Over-broad scope** | Too much work for one prompt/iteration | Split into smaller, focused prompts with clear boundaries | +| **Unstable dependencies** | External library or API keeps changing | Pin dependencies; mock external services in tests | + +### The critical rule + +**When the loop isn't stabilizing, the problem is upstream -- fix the specifications, validation, or coordination rather than adding more passes.** + +Running more iterations when the system is not converging wastes time and compute. Instead: +1. Stop the iteration loop +2. Analyze the non-convergence pattern +3. Fix the root cause (usually specs or validation) +4. Resume the iteration loop + +--- + +## 4. Test Pass Rate as Convergence Signal + +Test pass rate is the most reliable quantitative convergence signal. Track these metrics: + +### Metrics to monitor + +``` +| Iteration | Tests | Pass | Fail | Skip | Pass Rate | Delta | +|-----------|-------|------|------|------|-----------|-------| +| 1 | 45 | 30 | 15 | 0 | 66.7% | -- | +| 2 | 62 | 50 | 12 | 0 | 80.6% | +13.9 | +| 3 | 78 | 70 | 8 | 0 | 89.7% | +9.1 | +| 4 | 85 | 82 | 3 | 0 | 96.5% | +6.8 | +| 5 | 88 | 87 | 1 | 0 | 98.9% | +2.4 | +``` + +### What to look for + +| Pattern | Meaning | Action | +|---------|---------|--------| +| **Test count increasing** | Agent is adding coverage | Good -- system is maturing | +| **Pass rate approaching 100%** | Implementation matches specs | Good -- approaching convergence | +| **Fewer failures per iteration** | Each pass fixes more than it breaks | Good -- healthy convergence | +| **Pass rate plateaus < 100%** | Some tests consistently fail | Ceiling -- investigate failing tests | +| **Test count decreasing** | Agent is deleting tests | Bad -- investigate why; may be deleting inconvenient tests | +| **Pass rate oscillating** | Fixes in one area break another | Non-convergence -- check for conflicting specs | + +### Automated convergence check + +```bash +# After each iteration, check convergence signals +echo "=== Convergence Check ===" + +# 1. Lines changed (should be decreasing) +git diff --stat HEAD~1 + +# 2. Test results (should be improving) +{TEST_COMMAND} 2>&1 | tail -5 + +# 3. Build health (should always pass) +{BUILD_COMMAND} 2>&1 | tail -3 + +# 4. Files changed (should be decreasing) +git diff --name-only HEAD~1 | wc -l +``` + +--- + +## 5. Forward Progress Metrics + +For large projects where full convergence takes many iterations, track forward progress toward eventual convergence. + +### Spec requirement coverage + +The percentage of spec requirements with passing tests: + +``` +Spec Requirements Coverage: + spec-auth.md: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 95% (19/20 requirements) + spec-data.md: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 80% (16/20 requirements) + spec-ui.md: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 55% (11/20 requirements) + spec-api.md: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 70% (14/20 requirements) + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + Overall: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 75% (60/80 requirements) +``` + +### Forward progress signals + +| Metric | Healthy Trend | Unhealthy Trend | +|--------|--------------|-----------------| +| **Requirements with passing tests** | Increasing each iteration | Flat or decreasing | +| **Total test count** | Increasing | Flat or decreasing | +| **DONE tasks in impl tracking** | Increasing | Flat with BLOCKED tasks growing | +| **Open issues** | Decreasing | Increasing or flat | +| **Dead ends documented** | Increasing slightly (learning) | Exploding (thrashing) | + +### Iteration velocity + +Track how much progress each iteration makes: + +``` +| Iteration | Requirements Met | New This Iteration | Velocity | +|-----------|-----------------|-------------------|----------| +| 1 | 15/80 | 15 | 15 | +| 2 | 30/80 | 15 | 15 | +| 3 | 48/80 | 18 | 18 | +| 4 | 60/80 | 12 | 12 | +| 5 | 68/80 | 8 | 8 | +| 6 | 73/80 | 5 | 5 | +| 7 | 76/80 | 3 | 3 | +``` + +Velocity should decrease over time (easy requirements first, hard ones last), but should never hit zero. Zero velocity = ceiling. + +--- + +## 6. When to Stop Iterating + +### Stop conditions (convergence reached) + +Stop the iteration loop when ANY of these are true: + +1. **Completion signal emitted:** Agent outputs `` +2. **Changes are trivial:** Last iteration changed fewer than ~20 lines, all formatting/comments +3. **Test pass rate is stable:** Pass rate has been 95%+ for 2+ consecutive iterations +4. **All exit criteria met:** Every `[ ]` in the exit criteria checklist is `[x]` +5. **Forward progress stalled positively:** All spec requirements have passing tests + +### Continue conditions (not yet converged) + +Continue iterating when ALL of these are true: + +1. Changes are still substantial (behavior changes, not just formatting) +2. Test pass rate is still improving +3. There are still TODO or IN_PROGRESS tasks in impl tracking +4. The iteration count is under the maximum + +### Investigate conditions (possible ceiling) + +Pause and investigate when ANY of these are true: + +1. Changes are small but tests are NOT passing +2. Agent is retrying the same approach repeatedly +3. BLOCKED tasks are accumulating in impl tracking +4. Test pass rate is oscillating (up-down-up-down) +5. Agent is producing error messages about dependencies or tooling + +--- + +## 7. Monitoring During Iteration Loops + +### What to monitor in real time + +``` ++------------------------------------------------------+ +| Convergence Dashboard | ++------------------------------------------------------+ +| Iteration: 4/10 | +| Lines changed: 45 (prev: 112, trend: decreasing) | +| Files changed: 3 (prev: 8, trend: decreasing) | +| Test pass rate: 94.2% (prev: 87.1%, trend: up) | +| Tests: 82 total (prev: 75, trend: up) | +| BLOCKED tasks: 0 (prev: 1, trend: down) | +| Status: CONVERGING | ++------------------------------------------------------+ +``` + +### Monitoring commands + +```bash +# Quick convergence check after each iteration +echo "--- Lines changed ---" +git diff --stat HEAD~1 | tail -1 + +echo "--- Files changed ---" +git diff --name-only HEAD~1 | wc -l + +echo "--- Test results ---" +{TEST_COMMAND} --summary 2>&1 | tail -3 + +echo "--- Impl tracking status ---" +grep -c "BLOCKED\|IN_PROGRESS\|TODO\|DONE" context/impl/impl-*.md +``` + +### Automated alerts + +Set up alerts for non-convergence signals: + +| Alert | Trigger | Action | +|-------|---------|--------| +| **Oscillation** | Lines changed increased vs previous iteration | Pause; check for conflicting changes | +| **Stall** | Lines changed < 5 but tests still failing | Pause; likely a ceiling | +| **Regression** | Test pass rate decreased | Pause; investigate what broke | +| **Runaway** | Lines changed > 500 for 3+ iterations | Pause; scope may be too broad | + +--- + +## 8. Non-Convergence Recovery + +When you detect non-convergence, follow this recovery process: + +### Step 1: Stop the iteration loop + +Do not keep running. More iterations will not help. + +### Step 2: Diagnose the root cause + +```markdown +## Non-Convergence Diagnosis + +### Symptoms +- [ ] Changes are flat (not decreasing) +- [ ] Changes are oscillating (up-down-up-down) +- [ ] Agent is retrying failed approaches +- [ ] Tests are oscillating (passing then failing) +- [ ] Multiple agents changing the same files + +### Root Cause Analysis +1. Check specs: Are requirements clear and unambiguous? +2. Check validation: Can the agent verify correctness? +3. Check file ownership: Are agents conflicting? +4. Check scope: Is the prompt trying to do too much? +5. Check dependencies: Are external resources available? +``` + +### Step 3: Fix the root cause + +| Root Cause | Fix | +|-----------|-----| +| Fuzzy specs | Rewrite ambiguous requirements with concrete acceptance criteria | +| Weak validation | Add build/test/lint gates to the prompt | +| File conflicts | Add file ownership tables; dispatch subagents with `isolation: "worktree"` via the Agent tool | +| Over-broad scope | Split into smaller prompts; reduce concurrent agents | +| External dependency | Mock the dependency; or resolve it before resuming | + +### Step 4: Resume the iteration loop + +After fixing the root cause, resume from where you stopped. Do NOT restart from scratch -- git history preserves all progress. + +```bash +# Resume with the same prompt, possibly fewer remaining iterations +iteration-loop context/prompts/003-generate-impl-from-plans.md -n 5 -t 1h +``` + +--- + +## 9. Convergence and Revision + +Revision directly improves convergence by making specs more complete: + +``` +Without revision: + Iteration 1: 200 lines, 5 manual fixes -> specs unchanged + Iteration 2: 180 lines, 4 manual fixes -> specs unchanged + Iteration 3: 170 lines, 4 manual fixes -> NOT converging + +With revision: + Iteration 1: 200 lines, 5 manual fixes -> specs updated with 5 new requirements + Iteration 2: 100 lines, 2 manual fixes -> specs updated with 2 new requirements + Iteration 3: 50 lines, 0 manual fixes -> CONVERGING +``` + +**Frequent manual fixes without revision = non-convergence.** The iteration loop keeps producing the same bugs because nothing in the specs prevents them. + +--- + +## Cross-References + +- **Convergence patterns reference:** See `references/convergence-patterns.md` for the complete convergence pattern catalog with examples. +- **Revision:** See `bp:revision` skill for how tracing bugs to specs improves convergence. +- **Prompt pipeline:** See `bp:prompt-pipeline` skill for designing prompts with proper exit criteria and completion signals. +- **Validation-first design:** See `bp:validation-first` skill for building validation gates that provide convergence signals. +- **Impl tracking:** See `bp:impl-tracking` skill for tracking progress and detecting ceiling conditions. diff --git a/plugins/JuliusBrussee/blueprint/skills/design-system/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/design-system/SKILL.md new file mode 100644 index 0000000..ce37ec6 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/design-system/SKILL.md @@ -0,0 +1,525 @@ +--- +name: design-system +description: | + How to write and maintain a DESIGN.md in the 9-section Google Stitch format. + Covers the 9-section structure, design token conventions, quality standards, + integration with blueprints and build tasks, revision patterns, and collection import. + Trigger phrases: "design system", "DESIGN.md", "visual design spec", + "design tokens", "create design system", "import design system", + "visual identity", "UI spec", "design language" +--- + +# Design System: DESIGN.md for AI Agents + +## Core Principle: DESIGN.md Describes WHAT It Looks Like, Not HOW to Build It + +DESIGN.md is the visual equivalent of blueprints. It defines the project's visual language โ€” colors, typography, spacing, components, responsive behavior โ€” in a format AI agents can read and apply consistently. It is a **parallel constraint layer** that all DABI phases consult. + +| Document | Defines | Audience | +|----------|---------|----------| +| CLAUDE.md | How to build the project | Coding agents | +| Blueprints | What must be true (behavior) | All agents | +| **DESIGN.md** | **What it looks like (visual)** | **UI-building agents** | +| Plans | How to build it (tasks) | Builder agents | + +### Why a Dedicated Design System Document? + +Without DESIGN.md, visual decisions scatter across blueprints, plans, and code: +- Colors get hardcoded differently per component +- Typography choices vary between agents and sessions +- Spacing becomes inconsistent across the UI +- New components reinvent patterns that already exist + +DESIGN.md centralizes these decisions. Every agent reads it before writing UI code. + +--- + +## The 9-Section Stitch Format + +DESIGN.md follows the [Google Stitch format](https://stitch.withgoogle.com/docs/design-md/overview/) โ€” 9 sections that together define a complete visual language. Every DESIGN.md must contain all 9 sections. + +### Section 1: Visual Theme & Atmosphere + +The design philosophy, mood, and overall aesthetic. Use evocative, specific language โ€” not generic terms like "clean and modern." + +```markdown +## 1. Visual Theme & Atmosphere + +This is a warm editorial experience built on natural materials. Think: a well-curated +bookshop with soft overhead lighting and carefully chosen display shelves. The density +is low โ€” generous whitespace signals confidence and clarity. Every element earns its +place; nothing decorative exists without functional purpose. + +**Key attributes:** Warm, unhurried, editorial, confident +**Density:** Low โ€” generous whitespace, single-column focus +**Personality:** Thoughtful librarian, not flashy storefront +``` + +**What good looks like:** A new designer reading this section could sketch a rough layout without seeing any other section. + +**Anti-pattern:** "Clean, modern, and professional" โ€” this describes nothing specific. + +### Section 2: Color Palette & Roles + +Every color needs three things: a semantic name, a hex value, and a functional role. + +```markdown +## 2. Color Palette & Roles + +### Primary +| Name | Hex | Role | +|------|-----|------| +| Terracotta Brand | #c96442 | Primary CTA, active states, brand anchors | +| Terracotta Hover | #b85838 | Hover/pressed state for primary actions | + +### Neutral +| Name | Hex | Role | +|------|-----|------| +| Near Black | #141413 | Primary text, headings | +| Olive Gray | #5e5d59 | Secondary text, captions | +| Parchment | #f5f4ed | Page background, default canvas | +| Ivory White | #ffffff | Card surfaces, overlays | + +### Semantic +| Name | Hex | Role | +|------|-----|------| +| Success Green | #2d7d46 | Confirmation, success states | +| Warning Amber | #c27217 | Warnings, attention needed | +| Error Red | #c24132 | Errors, destructive actions | +| Info Blue | #3b6fb5 | Informational states, links | + +### Dark Mode (if applicable) +| Light Name | Dark Equivalent | Hex | +|------------|----------------|-----| +| Parchment | Deep Charcoal | #1a1a1a | +| Near Black | Off White | #e8e8e8 | +``` + +**Rules:** +- Every hex value must be verified against the actual design or live site +- Every color must have a clear functional role โ€” no orphan colors +- Name colors semantically (by role), not by hue ("Primary CTA" not "Orange") +- If dark mode exists, map every light color to its dark equivalent + +### Section 3: Typography Rules + +Complete type hierarchy with specific values โ€” no "roughly 16px" or "medium weight." + +```markdown +## 3. Typography Rules + +### Font Stack +- **Display/Heading:** "Anthropic Serif", Georgia, "Times New Roman", serif +- **Body:** "Anthropic Sans", -apple-system, BlinkMacSystemFont, sans-serif +- **Code:** "Anthropic Mono", "SF Mono", "Fira Code", monospace + +### Type Scale +| Level | Size | Weight | Line Height | Letter Spacing | Font | +|-------|------|--------|-------------|----------------|------| +| H1 | 48px / 3rem | 500 | 1.10 | -0.02em | Serif | +| H2 | 36px / 2.25rem | 500 | 1.15 | -0.01em | Serif | +| H3 | 24px / 1.5rem | 500 | 1.25 | 0 | Serif | +| H4 | 20px / 1.25rem | 600 | 1.30 | 0 | Sans | +| Body | 16px / 1rem | 400 | 1.60 | 0 | Sans | +| Small | 14px / 0.875rem | 400 | 1.50 | 0.01em | Sans | +| Caption | 12px / 0.75rem | 500 | 1.40 | 0.02em | Sans | + +### Principles +- Headings use serif for warmth and authority +- Body text uses sans-serif for readability at small sizes +- Maximum line length: 65ch for body text +- Minimum font size: 14px (never go below) +``` + +**Rules:** +- Every level in the scale must have all 5 values (size, weight, line-height, letter-spacing, font) +- Use rem alongside px for accessibility +- Include font stack fallbacks + +### Section 4: Component Stylings + +Concrete styling for common components including interaction states. + +```markdown +## 4. Component Stylings + +### Buttons +**Primary:** +- Background: Terracotta Brand (#c96442) +- Text: Ivory White (#ffffff), 16px Sans, weight 500 +- Padding: 12px 24px +- Border radius: 8px +- Hover: Terracotta Hover (#b85838), translateY(-1px), shadow-sm +- Active: translateY(0), shadow-none +- Disabled: opacity 0.5, cursor not-allowed +- Transition: all 150ms ease-out + +**Secondary:** +- Background: transparent +- Border: 1px solid Olive Gray (#5e5d59) +- Text: Near Black (#141413) +- Hover: background Parchment (#f5f4ed) + +### Cards +- Background: Ivory White (#ffffff) +- Border: 1px solid rgba(0,0,0,0.06) +- Border radius: 12px +- Padding: 24px +- Shadow: 0 1px 3px rgba(0,0,0,0.04) +- Hover: shadow 0 4px 12px rgba(0,0,0,0.08), translateY(-2px) + +### Inputs +- Border: 1px solid #d0d0d0 +- Border radius: 8px +- Padding: 10px 14px +- Focus: border Terracotta Brand, ring 2px rgba(201,100,66,0.2) +- Error: border Error Red, ring 2px rgba(194,65,50,0.2) + +### Navigation +... +``` + +**Rules:** +- Include hover, focus, active, and disabled states +- Specify transition durations and easing +- Include touch-target minimum sizes (44x44px) + +### Section 5: Layout Principles + +Spacing system, grid, containers, and whitespace philosophy. + +```markdown +## 5. Layout Principles + +### Spacing Scale (base: 4px) +| Token | Value | Usage | +|-------|-------|-------| +| space-1 | 4px | Tight gaps, icon margins | +| space-2 | 8px | Related element spacing | +| space-3 | 12px | Component internal padding | +| space-4 | 16px | Standard gap between elements | +| space-6 | 24px | Section padding, card padding | +| space-8 | 32px | Between major sections | +| space-12 | 48px | Page-level vertical rhythm | +| space-16 | 64px | Hero/banner spacing | + +### Grid +- Max content width: 1200px +- Column count: 12 +- Gutter: 24px (space-6) +- Margin: 16px mobile, 24px tablet, auto desktop + +### Border Radius Scale +| Token | Value | Usage | +|-------|-------|-------| +| radius-sm | 4px | Badges, tags | +| radius-md | 8px | Buttons, inputs | +| radius-lg | 12px | Cards, panels | +| radius-xl | 16px | Modals, dialogs | +| radius-full | 9999px | Avatars, pills | +``` + +### Section 6: Depth & Elevation + +Shadow system and visual layering. + +```markdown +## 6. Depth & Elevation + +### Shadow Scale +| Level | Value | Usage | +|-------|-------|-------| +| shadow-none | none | Flat elements | +| shadow-sm | 0 1px 2px rgba(0,0,0,0.04) | Subtle lift (cards at rest) | +| shadow-md | 0 4px 12px rgba(0,0,0,0.08) | Hover states, active cards | +| shadow-lg | 0 8px 24px rgba(0,0,0,0.12) | Dropdowns, popovers | +| shadow-xl | 0 16px 48px rgba(0,0,0,0.16) | Modals, dialogs | + +### Surface Hierarchy +1. **Base** โ€” page background (Parchment) +2. **Raised** โ€” cards, panels (Ivory White + shadow-sm) +3. **Floating** โ€” dropdowns, tooltips (Ivory White + shadow-lg) +4. **Overlay** โ€” modals, dialogs (Ivory White + shadow-xl + scrim) +``` + +### Section 7: Do's and Don'ts + +Concrete examples with code โ€” not just prose rules. + +```markdown +## 7. Do's and Don'ts + +### DO: Use semantic color names +```css +/* Good */ +.button-primary { background: var(--color-terracotta-brand); } +``` + +### DON'T: Hardcode color values +```css +/* Bad */ +.button-primary { background: #c96442; } +``` + +### DO: Follow the spacing scale +```css +/* Good โ€” uses scale */ +.card { padding: var(--space-6); margin-bottom: var(--space-8); } +``` + +### DON'T: Use arbitrary spacing +```css +/* Bad โ€” 19px is not on the scale */ +.card { padding: 19px; margin-bottom: 37px; } +``` + +### DO: Include all interaction states +### DON'T: Skip hover/focus states on interactive elements +### DO: Use the type scale for all text +### DON'T: Introduce new font sizes not in the scale +``` + +### Section 8: Responsive Behavior + +Breakpoints, mobile patterns, and adaptation rules. + +```markdown +## 8. Responsive Behavior + +### Breakpoints +| Name | Width | Target | +|------|-------|--------| +| mobile | < 640px | Phones | +| tablet | 640โ€“1024px | Tablets, small laptops | +| desktop | > 1024px | Laptops, monitors | + +### Touch Targets +- Minimum interactive element size: 44x44px +- Minimum spacing between targets: 8px + +### Mobile Adaptations +- Navigation collapses to hamburger menu below 640px +- Cards stack single-column below 640px +- Font sizes: H1 reduces to 32px on mobile, H2 to 28px +- Side padding: 16px on mobile, 24px tablet, auto-center desktop + +### Behavior Patterns +- Horizontal scrolling: never (use stacking or truncation) +- Images: responsive with srcset, max-width: 100% +- Tables: horizontal scroll wrapper below tablet breakpoint +``` + +### Section 9: Agent Prompt Guide + +How AI agents should use this document when generating UI. + +```markdown +## 9. Agent Prompt Guide + +### Quick Reference +- Primary CTA color: Terracotta Brand (#c96442) +- Background: Parchment (#f5f4ed) +- Heading font: Serif, weight 500 +- Body font: Sans, weight 400 +- Standard spacing: 24px (space-6) +- Card radius: 12px (radius-lg) + +### How to Use This Document +1. Before writing any UI code, read the full DESIGN.md +2. Reference specific section names when implementing: "Following Section 4: Buttons" +3. Use design token names in CSS (var(--color-terracotta-brand)), not raw hex values +4. Check Section 7 (Do's and Don'ts) before submitting +5. If a component is not covered, create it following existing patterns and flag for DESIGN.md update + +### Example Component Prompt +"Create a hero section on Parchment (#f5f4ed) with a headline at H1 scale +(48px Serif weight 500, line-height 1.10). Use Near Black (#141413) text. +Add a subtitle in Olive Gray (#5e5d59) at Body scale (16px Sans, line-height 1.60). +Place a Terracotta Brand (#c96442) primary button with Ivory text, radius-md (8px)." + +### Iteration Guide +- Change one component at a time +- Reference specific color names and token values +- Describe the component's state (default, hover, active, disabled) +- Specify responsive behavior for the component +``` + +--- + +## Design Token Conventions + +Tokens are the bridge between DESIGN.md and code. Consistent naming ensures agents can translate design specs into CSS/Tailwind variables. + +### Naming Pattern + +``` +--{category}-{name}[-{modifier}] +``` + +| Category | Examples | +|----------|---------| +| `color-` | `--color-terracotta-brand`, `--color-near-black`, `--color-success-green` | +| `space-` | `--space-1`, `--space-4`, `--space-8` | +| `text-` | `--text-h1`, `--text-body`, `--text-caption` | +| `radius-` | `--radius-sm`, `--radius-md`, `--radius-lg` | +| `shadow-` | `--shadow-sm`, `--shadow-md`, `--shadow-lg` | +| `font-` | `--font-serif`, `--font-sans`, `--font-mono` | + +### Mapping to CSS Custom Properties + +DESIGN.md tokens map directly to CSS custom properties: +```css +:root { + --color-terracotta-brand: #c96442; + --space-6: 24px; + --radius-lg: 12px; + --shadow-sm: 0 1px 2px rgba(0,0,0,0.04); +} +``` + +### Mapping to Tailwind + +When using Tailwind, DESIGN.md tokens map to `tailwind.config.js` extensions. The builder agent should configure this once and reference throughout. + +--- + +## Integration with Blueprints + +When DESIGN.md exists and blueprints contain UI requirements, acceptance criteria should reference design tokens by section and name. This creates a traceable chain: + +``` +DESIGN.md โ†’ Blueprint acceptance criterion โ†’ Plan task โ†’ Implementation +``` + +### How to Reference + +| In Blueprint Acceptance Criteria | Design Reference | +|----------------------------------|-----------------| +| "CTA button uses primary brand styling" | DESIGN.md Section 4: Buttons, primary variant | +| "Headings follow the type hierarchy" | DESIGN.md Section 3: Type Scale | +| "Cards have subtle resting elevation" | DESIGN.md Section 6: shadow-sm | +| "Layout uses the standard grid" | DESIGN.md Section 5: Grid | +| "Colors adapt for dark mode" | DESIGN.md Section 2: Dark Mode mapping | + +**Do NOT duplicate DESIGN.md content into blueprints.** Reference by section/token name only. If a color changes in DESIGN.md, blueprints should not need updating. + +### When No Design Reference Exists + +If a blueprint needs a visual pattern not in DESIGN.md, the acceptance criterion should note this: +```markdown +- [ ] Component uses a card-like container [DESIGN.md: pattern not yet defined โ€” flag for design update] +``` + +This tells the inspect phase to check whether DESIGN.md needs a new pattern. + +--- + +## Integration with Plans (Architect Phase) + +When the architect generates task descriptions for UI work, each task should include: + +```markdown +**Design Reference:** DESIGN.md Section {N} โ€” {section name} +``` + +This tells the task-builder which DESIGN.md sections to read before implementing. + +--- + +## Integration with Build Phase + +Task-builder agents follow this protocol for UI work: + +1. **Before implementing:** Read DESIGN.md (or the specific sections referenced in the task) +2. **During implementation:** Use design tokens, not hardcoded values +3. **In commit messages:** Note which DESIGN.md sections were followed +4. **If a new pattern is needed:** Implement it following existing DESIGN.md conventions and flag for design update + +--- + +## Revision Patterns + +When visual fixes are made manually (outside the DABI loop), `/bp:revise` traces them back to DESIGN.md: + +### Visual Fix Classification + +| Fix Type | DESIGN.md Action | +|----------|-----------------| +| Color change that should apply globally | Update DESIGN.md Section 2 with corrected value | +| New component pattern not in DESIGN.md | Add to DESIGN.md Section 4 | +| Spacing adjustment revealing wrong scale | Update DESIGN.md Section 5 scale | +| Typography fix | Update DESIGN.md Section 3 type scale | +| Responsive behavior change | Update DESIGN.md Section 8 | + +### Revision Protocol + +1. Identify the visual change in the diff +2. Check if DESIGN.md covers this pattern +3. If not covered: add the pattern to the appropriate section +4. If covered but wrong: update the token/value +5. Log the change to `context/designs/design-changelog.md` + +--- + +## Collection Import + +The [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) repository contains 54+ curated design systems extracted from real products. These serve as starting points. + +### Import Workflow + +1. **Choose a template:** `vercel`, `claude`, `stripe`, `github`, `linear`, etc. +2. **Fetch the raw DESIGN.md** from the collection +3. **Present to the user** as a starting point โ€” not a finished product +4. **Walk through each section** for customization (brand colors, typography, specific component needs) +5. **Write the customized version** to project root + +### After Import + +The imported DESIGN.md becomes the project's own. Future updates are made directly โ€” the import is a seed, not a dependency. + +--- + +## Quality Standards + +### Completeness Checklist + +- [ ] All 9 sections present and non-empty +- [ ] Every color has: semantic name + hex value + functional role +- [ ] Complete typography table (all 5 values per level) +- [ ] Component stylings include hover, focus, active, disabled states +- [ ] Spacing scale is defined with consistent base unit +- [ ] Shadow/elevation scale is defined +- [ ] Breakpoints have specific pixel values +- [ ] Agent Prompt Guide has quick reference and example prompts + +### Specificity Requirements + +Every value in DESIGN.md must be concrete and unambiguous: + +| Too Vague | Specific Enough | +|-----------|----------------| +| "a warm blue" | `#3b6fb5` (Info Blue) | +| "medium spacing" | `24px` (space-6) | +| "slightly rounded" | `8px` (radius-md) | +| "subtle shadow" | `0 1px 2px rgba(0,0,0,0.04)` (shadow-sm) | +| "large heading" | `48px / 3rem, weight 500, line-height 1.10` | + +### Consistency Rules + +- Tokens used in Section 4 (Components) must exist in Sections 2, 3, 5, 6 +- Dark mode mappings must cover every color used in components +- Responsive changes must reference defined breakpoints +- All spacing values must be multiples of the base unit + +--- + +## Anti-Patterns + +1. **Generic atmosphere** โ€” "Clean, modern, professional" describes every SaaS app and none +2. **Missing interaction states** โ€” A button without hover/focus is incomplete +3. **Orphan colors** โ€” Colors defined in the palette but never used in components +4. **Arbitrary spacing** โ€” Values that don't follow the spacing scale +5. **Missing dark mode** โ€” If the app supports dark mode, every light color needs a mapping +6. **Hex-only references in components** โ€” Use semantic names, not raw values +7. **No Agent Prompt Guide** โ€” Section 9 is what makes DESIGN.md actionable for AI agents +8. **Duplicating DESIGN.md into blueprints** โ€” Reference by section/token name only diff --git a/plugins/JuliusBrussee/blueprint/skills/documentation-inversion/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/documentation-inversion/SKILL.md new file mode 100644 index 0000000..e616845 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/documentation-inversion/SKILL.md @@ -0,0 +1,453 @@ +--- +name: documentation-inversion +description: > + Inverts the traditional documentation flow from code-to-wiki-for-humans (which rots) into + code-to-CLAUDE.md-to-skills-for-agents (which stays current). Each module gets a machine-readable + CLAUDE.md, navigation skills teach agents how to explore libraries, and plugins package skills for + on-demand loading. Documentation structured for machine consumption -- hierarchical, cross-referenced, + with clear entry points -- rather than narrative human reading. This is a fundamental shift: build + documentation for agents, not people. + Triggers: "documentation inversion", "skills as docs", "living documentation", + "docs for agents", "machine-readable docs", "agent-first documentation". +--- + +# Documentation Inversion + +Traditional documentation drifts out of sync because it lives separately from the code. Documentation inversion places guidance directly in the codebase, structured for agent consumption, so that AI can explore the source and find current information on demand. + +## Core Principle + +> **Structure documentation for programmatic navigation -- hierarchical, cross-referenced, with +> explicit entry points -- so that AI agents can find what they need without human guidance.** + +Traditional documentation assumes a human reader who will browse, search, and interpret context. +Agent-first documentation assumes a machine reader that needs: explicit entry points, structured +hierarchies, cross-references it can follow programmatically, and guidance on what to explore next. + +--- + +## The Problem: Traditional Documentation Rots + +### Traditional Flow + +``` +Developer ships a feature โ†’ Writes a wiki article explaining it + โ†“ + Weeks or months elapse + โ†“ + Another developer refactors the feature + โ†“ + The wiki article is never revised + โ†“ + A third developer (or an agent) follows the stale article + โ†“ + Incorrect assumptions, wasted effort, subtle bugs +``` + +**Why it rots:** +- Documentation is a second-class artifact -- the incentive is to ship code, not update docs +- The audience (humans) may not notice staleness until they hit a problem +- There is no automated validation that docs match code +- Docs live in a separate system (wiki, Notion) disconnected from the codebase +- Nobody owns documentation maintenance as a primary responsibility + +### The Cost of Rot + +- New team members learn wrong patterns from stale docs +- AI agents given stale docs produce code based on outdated assumptions +- Time spent debugging issues caused by following outdated guidance +- Tribal knowledge accumulates in chat, not in any durable format + +--- + +## The Solution: Inverted Documentation Flow + +### Inverted Flow + +``` +Developer modifies a module โ†’ Updates the co-located CLAUDE.md in the same PR + โ†“ + Navigation skill describes HOW to explore, not WHAT exists + โ†“ + Plugin bundles skills so agents can load them on demand + โ†“ + Agent enters the module โ†’ loads skill โ†’ reads live source code + โ†“ + Guidance stays accurate because the source itself is the authority +``` + +**Why it stays current:** +- CLAUDE.md files live *in the codebase*, next to the code they describe +- They are loaded automatically by AI agents when entering a directory +- Skills teach agents *how to explore*, not *what the code currently does* -- so they stay + accurate even as implementation details change +- The agent reads current source code, guided by the skill -- the source is the documentation +- Code review can enforce CLAUDE.md updates alongside code changes + +--- + +## Implementation Pattern + +### Step 1: Each Module Gets a CLAUDE.md + +Place a `CLAUDE.md` file at the root of each significant module, library, or directory. + +**What goes in a CLAUDE.md:** + +```markdown +# {Module Name} + +## Purpose +{One paragraph: what this module does and why it exists} + +## Entry Points +- `src/index.ts` -- Public API surface. Start here for understanding exports. +- `src/core/engine.ts` -- Core logic. Start here for understanding internals. + +## Architecture +{Brief description of how the module is structured internally} + +### Key Files +| File | Responsibility | +|------|---------------| +| `src/index.ts` | Public API, re-exports | +| `src/core/engine.ts` | Core processing engine | +| `src/core/types.ts` | Shared type definitions | +| `src/utils/helpers.ts` | Utility functions | + +## Conventions +- {Naming conventions specific to this module} +- {Error handling patterns} +- {Testing patterns} + +## Dependencies +- `{dependency-a}` -- Used for {purpose} +- `{dependency-b}` -- Used for {purpose} + +## Cross-References +- See `../shared/CLAUDE.md` for shared utilities +- See `../api/CLAUDE.md` for the API layer that consumes this module +``` + +**Key properties of a good CLAUDE.md:** +- **Hierarchical:** Organized as a tree the agent can navigate level by level +- **Cross-referenced:** Links to related CLAUDE.md files in other modules +- **Entry-point focused:** Tells the agent *where to start*, not *everything that exists* +- **Convention-documenting:** Captures patterns the agent should follow when modifying code +- **Brief:** Under 100 lines. Details live in the code itself. + +### Step 2: Create Navigation Skills + +A navigation skill teaches the agent *how to explore* a library or module. It does not +describe the library's current state -- it describes the *process* for understanding it. + +**Navigation Skill Template:** + +```markdown +--- +name: {library-name}-navigation +description: > + Teaches the agent how to navigate and understand the {library-name} library. + Triggers: "{library-name}", "how does {library-name} work", + "understand {library-name}". +--- + +# Navigating {Library Name} + +## Quick Orientation +1. Read `{root}/CLAUDE.md` for purpose and entry points +2. Read `{root}/src/index.ts` for the public API surface +3. Read `{root}/src/core/types.ts` for core type definitions + +## Understanding the Architecture +1. Start with the entry point identified in CLAUDE.md +2. Trace the main flow: {describe the primary call path} +3. Key abstractions: {list the 3-5 most important interfaces/classes} + +## Common Tasks + +### Adding a New Feature +1. Define types in `src/core/types.ts` +2. Implement core logic in `src/core/` +3. Export from `src/index.ts` +4. Add tests in `tests/` + +### Fixing a Bug +1. Identify the failing test or behavior +2. Trace from the public API inward +3. Core logic is in `src/core/engine.ts` +4. Edge cases are typically in `src/utils/helpers.ts` + +### Understanding a Specific Feature +1. Search for the feature name in `src/core/` +2. Read the test file for that feature -- tests document behavior +3. Check CLAUDE.md for any conventions specific to that area + +## Anti-Patterns to Avoid +- {Pattern to avoid and why} +- {Pattern to avoid and why} +``` + +**Why skills work better than static docs:** +- The skill tells the agent *what to do*, not what the code is +- The agent then reads the *current* source code to understand what the code is +- The process described in the skill remains valid even as the code changes +- It is a recipe, not a snapshot + +### Step 3: Package as a Plugin + +Bundle related navigation skills into a Claude Code plugin: + +``` +{library-name}-docs/ +โ”œโ”€โ”€ plugin.json +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ navigation/ + โ”‚ โ””โ”€โ”€ SKILL.md # How to navigate the library + โ”œโ”€โ”€ contributing/ + โ”‚ โ””โ”€โ”€ SKILL.md # How to contribute to the library + โ””โ”€โ”€ troubleshooting/ + โ””โ”€โ”€ SKILL.md # How to debug common issues +``` + +**plugin.json:** +```json +{ + "name": "{library-name}-docs", + "description": "Agent-first documentation for {library-name}", + "version": "1.0.0" +} +``` + +### Step 4: Agent Loads On Demand + +When an agent encounters the library: +1. The plugin's skills appear in the agent's available skill set +2. Agent loads the navigation skill when it needs to work with the library +3. Skill guides the agent to read CLAUDE.md files and explore current source +4. Agent builds understanding from current code, not stale documentation + +--- + +## The Hierarchy: Three Levels of Agent Documentation + +``` +Level 1: CLAUDE.md files (per-directory, auto-loaded) + โ†“ +Level 2: Navigation skills (per-library, loaded on demand) + โ†“ +Level 3: Plugin packages (distributable, installable) +``` + +### Level 1: CLAUDE.md Files + +- **Scope:** One directory or module +- **Loaded:** Automatically when the agent enters the directory +- **Content:** Purpose, entry points, conventions, cross-references +- **Maintained by:** The team that owns the module +- **Update trigger:** Code review -- CLAUDE.md changes alongside code changes + +### Level 2: Navigation Skills + +- **Scope:** One library or subsystem (may span multiple directories) +- **Loaded:** On demand when the agent needs to work with the library +- **Content:** Exploration process, common tasks, anti-patterns +- **Maintained by:** The team or developer who created the skill +- **Update trigger:** When the library's architecture changes (not every code change) + +### Level 3: Plugin Packages + +- **Scope:** A distributable collection of skills for a library or framework +- **Loaded:** Installed into a project, then skills load on demand +- **Content:** Multiple skills covering navigation, contributing, troubleshooting +- **Maintained by:** The library maintainers or community +- **Update trigger:** Major version changes or new skill additions + +--- + +## Designing CLAUDE.md for Machine Consumption + +### Structure for Machines, Not Narratives + +**Bad (human-narrative style):** +```markdown +This module was originally created in 2023 to handle user authentication. +Over time, we've added OAuth support, session management, and rate limiting. +The main file you'll want to look at is auth.ts, which contains most of the +logic. There's also a helpers file with some utility functions. +``` + +**Good (machine-structured style):** +```markdown +# Auth Module + +## Purpose +User authentication: login, logout, session management, OAuth, rate limiting. + +## Entry Points +- `src/auth.ts` -- Core auth logic (login, logout, verify) +- `src/oauth.ts` -- OAuth provider integrations +- `src/session.ts` -- Session management +- `src/rate-limit.ts` -- Rate limiting middleware + +## Key Types +- `AuthUser` in `src/types.ts` -- Authenticated user object +- `Session` in `src/types.ts` -- Session state +- `OAuthProvider` in `src/oauth.ts` -- Provider interface + +## Conventions +- All auth functions return `Result` -- never throw +- Sessions are stored in Redis -- see `src/session.ts` for connection setup +- Rate limits are per-IP by default -- see `src/rate-limit.ts` for config +``` + +### Key Differences + +| Dimension | Human-Oriented | Agent-Oriented | +|-----------|----------------|----------------| +| Layout | Flowing paragraphs and narrative arcs | Labeled sections, bullet lists, and tables | +| Starting points | Buried in prose ("you'll want to look at...") | Dedicated "Entry Points" section with exact file paths | +| Type information | Woven into explanatory text | Enumerated with source locations | +| Historical context | Prominent (gives humans background) | Absent (agents only need current state) | +| Coding standards | Scattered across wikis or tribal knowledge | Stated as explicit rules inside the CLAUDE.md | +| Links to related docs | Vague ("check the API docs") | Precise (`../api/CLAUDE.md#authentication`) | + +--- + +## CLAUDE.md Hierarchy and Inheritance + +CLAUDE.md files are hierarchical -- an agent entering a directory loads the CLAUDE.md from +that directory AND all parent directories up to the project root. + +``` +project/ +โ”œโ”€โ”€ CLAUDE.md # Project-wide conventions (loaded everywhere) +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md # Source code conventions (loaded in src/ and below) +โ”‚ โ”œโ”€โ”€ auth/ +โ”‚ โ”‚ โ”œโ”€โ”€ CLAUDE.md # Auth module specifics (loaded in auth/ and below) +โ”‚ โ”‚ โ””โ”€โ”€ oauth/ +โ”‚ โ”‚ โ””โ”€โ”€ CLAUDE.md # OAuth specifics (loaded only in oauth/) +โ”‚ โ””โ”€โ”€ api/ +โ”‚ โ””โ”€โ”€ CLAUDE.md # API module specifics +โ””โ”€โ”€ tests/ + โ””โ”€โ”€ CLAUDE.md # Testing conventions +``` + +**When an agent works in `src/auth/oauth/`**, it loads: +1. `project/CLAUDE.md` -- project-wide conventions +2. `project/src/CLAUDE.md` -- source code conventions +3. `project/src/auth/CLAUDE.md` -- auth module conventions +4. `project/src/auth/oauth/CLAUDE.md` -- OAuth-specific conventions + +**Use this hierarchy intentionally:** +- Project root: language, build commands, Git conventions, overall architecture +- `src/`: coding conventions, import patterns, error handling patterns +- Module level: module-specific entry points, types, dependencies +- Sub-module level: only when there are sub-module-specific conventions + +--- + +## Migration Path: From Wiki to Inverted Docs + +### Phase 1: Add CLAUDE.md Files (1-2 days) + +1. Identify the 5-10 most important modules in the codebase +2. Create a CLAUDE.md for each with: purpose, entry points, key files, conventions +3. Add a root CLAUDE.md with project-wide conventions +4. **Do not delete the wiki yet** -- CLAUDE.md files supplement it initially + +### Phase 2: Create Navigation Skills (1-2 days) + +1. For each major library or subsystem, create a navigation skill +2. Focus on the exploration process, not the current state +3. Package skills into a plugin +4. Test: give the agent a task in each library area and verify it loads the skill + +### Phase 3: Enforce Co-Location (Ongoing) + +1. Add to code review checklist: "Does this change need a CLAUDE.md update?" +2. When new modules are created, require a CLAUDE.md as part of the PR +3. When existing docs are found to be stale, update the CLAUDE.md (not the wiki) +4. Gradually, the CLAUDE.md files become the authoritative source + +### Phase 4: Deprecate the Wiki (When Ready) + +1. Audit: for each wiki page, verify the information exists in CLAUDE.md files or skills +2. Archive the wiki (do not delete -- it may have historical context worth preserving) +3. Redirect documentation questions to: "Read the CLAUDE.md in the relevant directory" + +--- + +## Measuring Documentation Health + +### Staleness Indicators + +| Signal | Meaning | +|--------|---------| +| CLAUDE.md not updated in 6+ months but code changed significantly | Documentation may be stale | +| Agent frequently ignores CLAUDE.md guidance | Guidance may be outdated or unhelpful | +| Agent asks clarifying questions about a module that has a CLAUDE.md | CLAUDE.md is missing key information | +| New team members still rely on tribal knowledge | CLAUDE.md files are incomplete | + +### Health Metrics + +- **Coverage:** What percentage of significant modules have a CLAUDE.md? +- **Freshness:** When was each CLAUDE.md last updated relative to its module's last code change? +- **Usefulness:** Do agents produce better output when CLAUDE.md files are present? +- **Completeness:** Does each CLAUDE.md have: purpose, entry points, key files, conventions? + +--- + +## Anti-Patterns + +### 1. CLAUDE.md as a Code Dump +**Problem:** CLAUDE.md lists every file and function in the module. +**Fix:** Focus on entry points and navigation, not exhaustive inventory. The agent can +read the directory listing itself. + +### 2. Narrative Prose Instead of Structure +**Problem:** CLAUDE.md reads like a blog post about the module's history. +**Fix:** Use tables, lists, and labeled sections. Agents parse structure, not stories. + +### 3. Duplicating Code Comments +**Problem:** CLAUDE.md repeats what is already in code comments and docstrings. +**Fix:** CLAUDE.md should describe the *module-level* view -- architecture, conventions, +entry points. Code comments handle the *function-level* view. + +### 4. Never Updating CLAUDE.md +**Problem:** CLAUDE.md is written once and never touched again. +**Fix:** Make CLAUDE.md updates part of the code review process. If you changed the +module's architecture, update the CLAUDE.md. + +### 5. One Giant CLAUDE.md at the Root +**Problem:** All documentation is in a single root CLAUDE.md file. +**Fix:** Use the hierarchy. Root CLAUDE.md has project-wide conventions; each module +has its own CLAUDE.md with module-specific guidance. This mirrors progressive disclosure. + +--- + +## Integration with SDD + +Documentation inversion is a natural extension of SDD's context architecture: + +| SDD Concept | Documentation Inversion Counterpart | +|------------|-----------------------------------| +| Context directory structure (specs/, plans/, impl/) | Per-module CLAUDE.md files co-located with source | +| Progressive disclosure (index file points to detail files) | CLAUDE.md hierarchy cascading from project root to leaf modules | +| Specifications as the source of truth | CLAUDE.md as the authoritative guidance artifact for each module | +| Skills encoding reusable procedures | Navigation skills encoding reusable exploration workflows | +| Plugins as a distribution mechanism | Documentation plugins bundling skills for installation into other projects | + +The key insight from SDD applies directly: **strong documentation enables agents to orient +themselves in unfamiliar code and contribute meaningfully without step-by-step human direction.** + +--- + +## Cross-References + +- **context-architecture** -- The progressive disclosure pattern that CLAUDE.md hierarchy implements +- **methodology** -- How documentation inversion fits into the broader Blueprint lifecycle +- **spec-writing** -- Specs and CLAUDE.md files share the same structural principles +- **brownfield-adoption** -- When adopting SDD on an existing codebase, CLAUDE.md files are step 1 +- **impl-tracking** -- Implementation tracking documents are a form of inverted documentation diff --git a/plugins/JuliusBrussee/blueprint/skills/impl-tracking/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/impl-tracking/SKILL.md new file mode 100644 index 0000000..628cd8d --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/impl-tracking/SKILL.md @@ -0,0 +1,436 @@ +--- +name: impl-tracking +description: | + Implementation tracking documents for maintaining living records of what was built, what is pending, + what failed, and what dead ends were explored. Covers the full tracking document template, dead ends + prevention, cross-iteration continuity, spec compaction, and inter-session feedback protocol. + Trigger phrases: "implementation tracking", "track progress", "session tracking", + "what did the agent do", "dead ends", "failed approaches" +--- + +# Implementation Tracking + +## Core Principle: Track Everything, Especially Failures + +Implementation tracking documents are **living records** that agents read and update every session. They serve as persistent memory across iterations, preventing duplicate work and preserving hard-won knowledge about what works and what does not. + +The most valuable information in an implementation tracking document is not what succeeded โ€” it is **what failed and why**. Dead ends documented today prevent agents from wasting hours retrying the same failed approaches tomorrow. + +--- + +## Why Implementation Tracking Matters + +| Purpose | What It Prevents | +|---------|-----------------| +| **Cross-iteration continuity** | Agents starting from scratch every session | +| **Dead end prevention** | Agents retrying approaches that already failed | +| **Progress visibility** | Humans not knowing what was done or what is left | +| **Test health awareness** | Agents not knowing current test state | +| **Issue tracking** | Known issues being forgotten between sessions | +| **File change tracking** | Uncertainty about what files were created or modified | + +Without implementation tracking, every agent session begins with expensive rediscovery. With it, agents resume exactly where the last session left off. + +--- + +## Full Implementation Tracking Document Template + +Use this template for every implementation tracking document: + +```markdown +# Implementation Tracking: {Domain or Scope} + +## Status: {IN_PROGRESS | COMPLETE | BLOCKED} + +**Last Updated:** {Date} +**Current Phase:** {Spec | Plan | Implement | Iterate | Monitor} +**Blocking Issues:** {None | Brief description of blockers} + +--- + +## Task Status + +| Task ID | Task | Status | Notes | +|---------|------|--------|-------| +| T-1 | {Task description} | DONE | {Completion notes} | +| T-2 | {Task description} | DONE | {Completion notes} | +| T-3 | {Task description} | IN_PROGRESS | {Current state, what remains} | +| T-4 | {Task description} | BLOCKED | {What is blocking, dependency} | +| T-5 | {Task description} | NOT_STARTED | {Prerequisites} | + +### Task Dependencies +- T-4 blockedBy T-3 (needs auth module before API integration) +- T-5 blockedBy T-3, T-4 + +--- + +## Files Created + +| File | Purpose | Spec Reference | +|------|---------|---------------| +| `src/auth/login.{ext}` | Login handler | spec-auth.md R1 | +| `src/auth/session.{ext}` | Session management | spec-auth.md R2 | +| `tests/auth/login.test.{ext}` | Login unit tests | spec-auth.md R1 AC1-3 | + +## Files Modified + +| File | Change | Reason | +|------|--------|--------| +| `src/app.{ext}` | Added auth middleware | spec-auth.md R3 | +| `src/config.{ext}` | Added session config | spec-auth.md R2 | + +--- + +## Issues & TODOs + +- [ ] **Issue:** Session expiry not tested under concurrent access โ€” need load test +- [ ] **TODO:** Add rate limiting to login endpoint (spec-api.md R7) +- [ ] **TODO:** Implement password reset flow (spec-auth.md R4, NOT_STARTED) +- [x] **Resolved:** TypeScript compilation error in session.ts โ€” fixed incorrect import path + +--- + +## Dead Ends & Failed Approaches + +### DE-1: JWT with asymmetric keys for session tokens +**What was attempted:** Implemented RS256 JWT tokens with public/private key pair. +**Root cause of failure:** Key rotation complexity exceeded the session management requirements. Added 200+ lines of key management code for no user-visible benefit. Symmetric HS256 with server-side session store is simpler and meets all spec criteria. +**Verdict:** Do not reattempt. Use symmetric tokens with server-side sessions instead. + +### DE-2: Redis for session storage +**What was attempted:** Used Redis as the session store backend. +**Root cause of failure:** Redis dependency adds operational complexity. The application's expected concurrent user count (< 10,000) is well within what a database-backed session store handles. Redis would be premature optimization. +**Verdict:** Do not reattempt unless concurrent user requirements change significantly (> 100,000). + +### DE-3: Cookie-based CSRF protection +**What was attempted:** Double-submit cookie pattern for CSRF. +**Root cause of failure:** Incompatible with the API's token-based auth flow. Clients send bearer tokens in headers, not cookies. CSRF protection is inherently handled by the token-based approach. +**Verdict:** Do not reattempt. Token-based auth does not need separate CSRF protection. + +--- + +## Test Health + +| Test Suite | Passing | Failing | Skipped | Line Coverage | +|------------|---------|---------|---------|---------------| +| Unit tests | 45 | 2 | 0 | 78% | +| Integration | 12 | 1 | 3 | n/a | +| E2E | 0 | 0 | 0 | n/a | + +### Failing Tests +- `tests/auth/session.test.{ext}:34` โ€” Session refresh fails when token is expired more than 24h. Needs spec clarification on refresh window. +- `tests/integration/api-auth.test.{ext}:89` โ€” Timeout on concurrent login test. Likely race condition in session creation. + +### Test Notes +- E2E tests not yet created (blocked on T-4: API integration) +- Integration test skip: 3 tests require external OAuth provider mock (TODO) + +--- + +## Session Log + +### Session 3 (current) +- Completed T-2 (session management) +- Started T-3 (API integration) โ€” 60% complete +- Discovered DE-3 (CSRF not needed with token auth) +- 2 new failing tests identified + +### Session 2 +- Completed T-1 (login handler) +- Discovered DE-1 (JWT asymmetric keys too complex) +- Discovered DE-2 (Redis premature for this scale) +- Test health: 38 pass, 0 fail + +### Session 1 +- Set up auth module structure +- Created initial test scaffolding +- Established file ownership: auth/ owned by auth-agent +``` + +--- + +## Dead Ends: The Most Critical Section + +**Dead ends prevent agents from retrying failed approaches.** This is the single most important function of implementation tracking. + +### Why Dead Ends Matter + +Without dead end documentation: +1. Agent encounters a problem in session 5 +2. Agent tries approach X โ€” spends 30 minutes, fails +3. Session ends +4. In session 6, a new agent encounters the same problem +5. Agent has no memory of session 5's failure +6. Agent tries approach X again โ€” wastes another 30 minutes +7. This repeats indefinitely + +With dead end documentation: +1. Agent encounters a problem in session 5 +2. Agent tries approach X โ€” spends 30 minutes, fails +3. Agent documents the dead end: what was tried, why it failed, what to do instead +4. In session 6, a new agent reads the dead end +5. Agent skips approach X and uses the recommended alternative +6. Problem solved in 5 minutes instead of 30 + +### Dead End Format + +Every dead end entry must include: + +```markdown +### DE-{N}: {Short description of the approach} +**What was attempted:** {Specific description of the approach taken} +**Root cause of failure:** {Why it did not work โ€” a clear technical explanation, not just "it broke"} +**Verdict:** Do not reattempt. {Recommended alternative, or conditions under which the approach might become viable} +``` + +### Rules for Dead Ends + +1. **Always document the root cause.** "It didn't work" is not useful. "Failed because the library's async API is incompatible with the synchronous middleware chain" is useful. +2. **Include the alternative.** What should be done instead? +3. **Be specific about conditions.** If a retry might make sense under different conditions, state those conditions explicitly. +4. **Never delete dead ends during compaction** unless they are older than 5 sessions and the underlying conditions have changed. + +--- + +## Cross-Iteration Continuity + +Implementation tracking documents are the primary mechanism for continuity between iteration loop passes and between human-initiated sessions. + +### How Agents Use Tracking Documents + +At the start of every iteration or session, the agent: + +1. **Reads the tracking document** to understand current state +2. **Checks task status** to identify the highest-priority unblocked work +3. **Reviews dead ends** to avoid retrying failed approaches +4. **Checks test health** to understand what is passing and failing +5. **Reviews open issues** for context on known problems + +At the end of every iteration or session, the agent: + +1. **Updates task status** for all tasks worked on +2. **Records new files** created or modified +3. **Documents any dead ends** discovered +4. **Updates test health** with current pass/fail counts +5. **Adds issues** for any new problems found +6. **Updates the session log** with a summary of work done + +### The Read-Work-Update Cycle + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ 1. Read impl tracking โ”‚ +โ”‚ 2. Identify highest-priority task โ”‚ +โ”‚ 3. Check dead ends for this area โ”‚ +โ”‚ 4. Implement โ”‚ +โ”‚ 5. Run validation gates โ”‚ +โ”‚ 6. Update impl tracking โ”‚ +โ”‚ 7. Commit โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ†“ (next iteration) +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ 1. Read impl tracking (updated) โ”‚ +โ”‚ 2. ... โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## Spec Compaction + +When implementation tracking files exceed approximately 500 lines, they become unwieldy for agents to process. Compaction compresses the file while preserving active context. + +### When to Compact + +- File exceeds 500 lines +- More than half the tasks are DONE +- Session log has more than 5 entries +- Dead ends section has entries older than 5 sessions that are no longer relevant + +### Compaction Process + +1. **Create archive:** Copy current file to `impl/archive/impl-{scope}-v{N}.md` +2. **Remove from active file:** + - Completed tasks (keep only a count: "12 tasks completed, see archive") + - Resolved issues (marked with [x]) + - Old session log entries (keep last 2-3 sessions) + - Dead ends older than 5 sessions IF the underlying conditions changed +3. **Preserve in active file:** + - All IN_PROGRESS and NOT_STARTED tasks + - All BLOCKED tasks with their blockers + - All open issues + - Recent dead ends (last 3-5 sessions) + - Current test health + - Active cross-references + - Files created/modified (keep all โ€” this is the file manifest) +4. **Target:** Under 500 lines in the active file +5. **Add archive reference:** + ```markdown + > **Archive:** Previous tracking history available in impl/archive/impl-all-v2.md + > 12 tasks completed in prior sessions. See archive for details. + ``` + +### Compaction Rules + +- **Never delete information** โ€” always archive first +- **Never remove active dead ends** โ€” they prevent retrying failures +- **Always keep the full file manifest** โ€” agents need to know what files exist +- **Preserve test health** โ€” agents need current state, not historical + +--- + +## Inter-Session Feedback Protocol + +For structured handoffs between sessions (especially when different humans or automation systems manage sessions), use the inter-session feedback protocol. + +### XML Format + +```xml + + 2026-03-14-session-3 + 2026-03-14T14:30:00Z + + + Implement session management + DONE + true + + Implemented session creation, validation, and refresh. + Added server-side session store with database backend. + Created 3 new files, modified 2 existing files. + + + + Proceed to API integration (T-3). Session module is ready. + + + + + API endpoint integration + PARTIAL + true + + Completed GET /users and POST /login endpoints. + PUT /users and DELETE /users not started. + + + Waiting for session management to stabilize (now done). + + + Continue with PUT/DELETE endpoints. All dependencies resolved. + + + + + OAuth provider integration + BLOCKED + false + + Investigation complete. OAuth provider requires API key registration. + + + Cannot proceed without OAuth API credentials. + Human action required: register application with OAuth provider. + + + Skip until credentials are available. Focus on other tasks. + + + +``` + +### Field Definitions + +| Field | Values | Purpose | +|-------|--------|---------| +| `status` | DONE, PARTIAL, BLOCKED | Current state of the work item | +| `files-modified` | true, false | Whether code was modified (helps humans prioritize review) | +| `summary` | Free text | What was accomplished โ€” be specific | +| `obstacles.kind` | NONE, TEMPORARY, PERMANENT | TEMPORARY = will resolve on its own; PERMANENT = requires human action | +| `next-steps` | Free text | What the next session should do with this item | + +### When to Use the Feedback Protocol + +- **Between human-managed sessions:** When a human starts each session and needs to know what happened +- **Automation handoffs:** When an orchestration system decides what to work on next +- **Work queue generation:** The `/bp:next-session` command consumes this feedback to generate prioritized work items + +> For the full session feedback protocol reference, see `references/session-feedback-protocol.md`. + +--- + +## Work Queue Handoff + +At the end of a session, generate a `plan-next-session.md` that prioritizes work for the next session: + +```markdown +# Next Session Work Queue + +## WI-1: Complete API endpoint integration +- **Category:** feature +- **Size:** M +- **Priority:** high +- **Spec reference:** plan-api.md +- **What to do:** Implement PUT /users and DELETE /users endpoints +- **Files to modify:** src/api/users.{ext}, tests/api/users.test.{ext} +- **Acceptance criteria:** + - [ ] PUT /users/{id} updates user record and returns 200 + - [ ] DELETE /users/{id} removes user and returns 204 + - [ ] Both endpoints require valid session token + +## WI-2: Fix failing session refresh test +- **Category:** bugfix +- **Size:** S +- **Priority:** medium +- **Spec reference:** plan-auth.md +- **What to do:** Investigate and fix session refresh failure for tokens expired > 24h +- **Files to modify:** src/auth/session.{ext}, tests/auth/session.test.{ext} +- **Acceptance criteria:** + - [ ] Session refresh test passes for tokens expired < 24h + - [ ] Clear error message for tokens expired > 24h (if that is the intended behavior) + +## WI-3: Create E2E test scaffolding +- **Category:** test +- **Size:** M +- **Priority:** medium +- **Spec reference:** plan-testing.md +- **What to do:** Set up E2E test framework and create smoke tests +- **Files to modify:** tests/e2e/setup.{ext}, tests/e2e/smoke.test.{ext} +- **Acceptance criteria:** + - [ ] E2E framework runs successfully + - [ ] Smoke test verifies application starts and login works +``` + +This removes the orientation cost at the start of each session โ€” agents begin productive work immediately. The next agent reads this file and begins working immediately on the highest-priority item. + +--- + +## Integration with Other Skills + +### With `bp:blueprint-writing` + +Implementation tracking references specs by requirement ID. When a task is completed, its acceptance criteria map back to spec requirements. When dead ends are found, they may reveal spec gaps that need revision. + +### With `bp:validation-first` + +Test health in the tracking document reflects validation gate results. Failing tests indicate which gates are not passing. The tracking document records which gates each task must clear. + +### With `bp:context-architecture` + +Implementation tracking documents live in `context/impl/`. When files grow too large, archive to `context/impl/archive/`. The CLAUDE.md in `context/impl/` instructs agents on tracking conventions. + +### With `bp:methodology` + +Implementation tracking is used primarily during the Implement and Iterate phases of DABI. The iteration loop reads and updates tracking documents every pass. The Monitor phase reviews tracking documents for progress signals. + +--- + +## Summary + +1. **Track everything, especially failures** โ€” dead ends are the most valuable information +2. **Use the template** โ€” consistent format lets agents parse tracking documents reliably +3. **Update every session** โ€” stale tracking is worse than no tracking +4. **Document dead ends with root causes** โ€” "it didn't work" is not useful; "failed because X, do Y instead" is +5. **Compact when large** โ€” archive resolved content, keep active files under 500 lines +6. **Use the feedback protocol** for structured handoffs between sessions +7. **Generate work queues** to eliminate discovery overhead at session start diff --git a/plugins/JuliusBrussee/blueprint/skills/methodology/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/methodology/SKILL.md new file mode 100644 index 0000000..8f290ea --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/methodology/SKILL.md @@ -0,0 +1,264 @@ +--- +name: methodology +description: | + Core Blueprint methodology โ€” the master skill that teaches the DABI lifecycle + and routes to all sub-skills. Covers the Specify Before Building principle, the scientific method analogy, + the four-phase DABI lifecycle, decision matrix for when to use Blueprint, and build pipeline analogy. + Trigger phrases: "use Blueprint", "blueprint methodology", "start Blueprint project", "blueprint methodology", + "how should I structure this project for AI agents" +--- + +# Blueprint Methodology + +## Core Principle: Specify Before Building + +**Always define what you want before telling agents how to build it. Go through a blueprint stage โ€” never jump straight from raw requirements to implementation.** + +Blueprint is a methodology for building software with AI coding agents that **puts blueprints at the center of the development process โ€” code is derived from them, not the other way around**. Whether starting from scratch or modernizing an existing system, the principle is the same: + +- **Greenfield projects:** reference material โ†’ blueprints โ†’ code +- **Rewrites:** old code โ†’ blueprints โ†’ new code + +In both cases, the blueprints become a living contract that agents consume to continuously build, validate, and refine the application. + +### Why Blueprints Are the First-Class Citizen + +| Property | Benefit | +|----------|---------| +| **Structured** | Organized as a navigable tree, enabling agents to load only what they need | +| **Human-legible** | Engineers can audit requirements at a higher level than code | +| **Stack-independent** | Decoupled from any single framework or language | +| **Independently evolvable** | Blueprints can be refined without touching implementation | +| **Verifiable** | Every requirement includes acceptance criteria agents can check | + +> **Key Insight:** Well-written blueprints with strong validation make your application reproducible โ€” any agent can rebuild it from the blueprints alone. Think of it as continuous regeneration. + +--- + +## The Scientific Method Analogy + +LLMs are inherently non-deterministic โ€” like running an experiment, each individual call may yield different results. But through the right methodology โ€” clear hypotheses, controlled conditions, and repeated trials โ€” we extract reliable, reproducible outcomes from a stochastic process. + +**Blueprint applies the scientific method to software construction โ€” hypothesize, test, observe, refine.** + +| Layer | Analogy | What It Does | +|-------|---------|-------------| +| **LLM calls** | Individual experiments | Each run may produce different results; no single output is authoritative | +| **Blueprints** | Hypotheses | Define what you expect to observe โ€” the predicted behavior | +| **Validation gates** | Controlled conditions | Ensure reproducibility by constraining what counts as a valid outcome | +| **Convergence loops** | Repeated trials | Build statistical confidence through successive passes | +| **Implementation tracking** | Lab notebook | Record what was tried, what worked, and what failed | +| **Revision** | Revising the hypothesis | When results contradict expectations, update the theory upstream | + +The outcome: a disciplined, repeatable engineering process layered on top of probabilistic generation. + +--- + +## The 5 DABI Phases + +DABI stands for **Draft, Architect, Build, Inspect**. Each phase has dedicated prompts that drive it. + +| Phase | Input | Output | AI Role | Human Role | +|-------|-------|--------|---------|------------| +| **Draft** | Source materials, domain knowledge, existing systems | Implementation-agnostic blueprints | Extract requirements, structure knowledge | Verify blueprints capture intent accurately | +| **Architect** | Blueprints + framework research | Framework-specific implementation plans | Design architecture, break down work, order steps | Approve architectural choices | +| **Build** | Plans + blueprints | Working code + tests + tracking docs | Write code, run tests, check against blueprints | Watch for drift and blockers | +| **Inspect** | Failed validations, gaps, manual fixes | Updated blueprints/plans via revision | Identify root causes, propagate fixes upstream | Evaluate outcomes, set priorities | +| **Monitor** | Running application, git history | Issues, anomalies, progress reports | Scan for regressions, surface metrics | Interpret reports, guide next steps | + +### Phase Transitions + +Each phase has **gate conditions** that must be met before moving to the next: + +1. **Draft โ†’ Architect:** All domains have blueprints with testable acceptance criteria. Human has reviewed for completeness. +2. **Architect โ†’ Build:** Plans reference blueprints, define implementation sequence, and include test strategies. Architecture decisions validated. +3. **Build โ†’ Inspect:** Code builds, tests pass at current coverage level, implementation tracking is up to date. +4. **Inspect โ†’ Monitor:** Convergence detected (changes decreasing iteration-over-iteration). Remaining changes are trivial. +5. **Monitor โ†’ Draft (cycle):** Gap found or new requirement identified. Revise blueprints and restart the cycle. + +The **Inspect** phase is where the human serves as **reviewer and decision-maker**, not hands-on coder. You monitor the process, request changes as needed, and make systemic improvements to blueprints and prompts. + +> For the full DABI phase reference, see `references/dabi-phases.md`. + +--- + +## Decision Matrix: When to Use Blueprint + +### Full Blueprint + +Use when the project has significant scope, evolving requirements, or needs autonomous agent execution. + +| Indicator | Threshold | +|-----------|-----------| +| Codebase size | 50+ source files | +| Requirements | Evolving, multi-domain | +| Agent coordination | Multi-agent or multi-prompt pipelines | +| Environment | Production, security-sensitive, brownfield | +| Team structure | Multi-team or cross-team | +| Execution mode | Long-running autonomous work (overnight, unattended) | + +**What you get:** Full DABI lifecycle, context directory with blueprints/plans/impl tracking, prompt pipeline, convergence loops, revision, validation gates. + +### Lightweight Blueprint + +Use when scope is moderate โ€” too complex for ad-hoc but not worth a full pipeline. + +| Indicator | Threshold | +|-----------|-----------| +| Codebase size | 5-50 files | +| Requirements | Mostly clear, focused | +| Agent coordination | Single agent, possibly with sub-agents | +| Execution mode | Interactive with occasional iteration loops | + +**What you do:** +1. Write a focused `context/blueprints/blueprint-task.md` capturing requirements +2. Add a `context/plans/plan-task.md` sequencing the implementation +3. Skip full DABI โ€” just run an iteration loop against the plan + +This is the "Blueprint floor" โ€” most of the benefit without the overhead of a full multi-phase pipeline. + +### Skip Blueprint + +Use when the task is trivially small. + +| Indicator | Threshold | +|-----------|-----------| +| Codebase size | Less than 5 files | +| Task type | One-off tools, simple bug fixes, exploratory prototypes | +| Implementation | Fits comfortably in one agent session without needing external references | + +**Heuristic:** If the whole task fits in one context window with room to spare, full Blueprint adds more overhead than value. + +### Growth Path + +Start with lightweight Blueprint even if the project is small. If the scope expands, you already have the structure in place to scale up. It is much harder to retrofit blueprints onto a large codebase than to grow a blueprint directory from the beginning. + +--- + +## The CI Pipeline Analogy + +Blueprint mirrors a **build pipeline** โ€” each stage transforms input into validated output, with feedback loops that propagate corrections upstream: + +``` +Traditional CI/CD: + Code โ†’ Build โ†’ Test โ†’ Deploy + +Blueprint AI Pipeline: + Blueprint Change + โ†’ Generate Plans (iteration loop) + โ†’ Generate Implementation (iteration loop) + โ†’ Validate (Tests + Review) + โ†’ Human Audit (Monitor & Steer) + โ†’ [Gap Found] + โ†’ Revise + โ†’ Blueprint Change (cycle repeats) +``` + +Every stage can run as an iteration loop โ€” the same prompt executed repeatedly until output stabilizes. The iteration loop is what transforms nondeterministic LLM output into predictable, validated software. + +### The Iteration Loop + +The iteration loop is the fundamental execution unit in Blueprint. Execute the same prompt against the same codebase multiple times until the delta between runs approaches zero. + +**Mechanics:** +1. Execute a prompt against the current codebase +2. The agent inspects git history and tracking documents to understand what has already been done +3. The agent applies changes and commits its progress +4. Return to step 1 + +**Convergence signal:** A shrinking volume of modifications across successive passes โ€” the diff gets smaller each time until only cosmetic changes remain. You are looking for diminishing returns, not absolute zero. + +**When the loop isn't stabilizing, the problem is upstream โ€” fix the inputs (specs, validation, coordination), not the iteration count.** + +If the diff is not shrinking between runs: +- Blueprints are ambiguous (agents interpret them differently each time) +- Validation criteria are too loose (the agent has no way to confirm it got things right) +- Multiple agents are overwriting each other's work (ownership boundaries are unclear) + +--- + +## Cross-References to Sub-Skills + +Blueprint is composed of techniques that work together. This methodology skill is the index โ€” each sub-skill below is self-contained but cross-references others. + +### Foundation Skills + +| Skill | Purpose | When to Use | +|-------|---------|-------------| +| `bp:blueprint-writing` | Write implementation-agnostic blueprints with testable acceptance criteria | Draft phase โ€” always the first step | +| `bp:context-architecture` | Organize context for progressive disclosure | Project setup and ongoing maintenance | +| `bp:impl-tracking` | Track implementation progress, dead ends, test health | Build and Inspect phases | +| `bp:validation-first` | Design validation gates agents can execute | All phases โ€” validation is continuous | + +### Pipeline Skills + +| Skill | Purpose | When to Use | +|-------|---------|-------------| +| `bp:prompt-pipeline` | Design numbered prompt pipelines for DABI | Setting up automation | +| `bp:revision` | Trace bugs back to blueprints and fix at the source | Inspect phase โ€” after finding gaps | +| `blueprint:brownfield-adoption` | Adopt Blueprint on existing codebases | Starting Blueprint on legacy projects | + +### Advanced Skills + +| Skill | Purpose | When to Use | +|-------|---------|-------------| +| `bp:peer-review` | Use a second agent to challenge the first | Quality gates, architecture review | +| `blueprint:speculative-pipeline` | Stagger pipeline stages for parallelism | Optimizing long pipelines | +| `bp:convergence-monitoring` | Detect convergence vs ceiling | Monitoring iteration loops | +| `blueprint:documentation-inversion` | Turn documentation into agent-consumable skills | Library/module documentation | + +### Integration with Existing Skills + +Blueprint works **with** existing skills, not as a replacement: + +| Existing Skill | Blueprint Integration | +|----------------|-----------------| +| `superpowers:brainstorming` | Use during blueprint generation to explore requirements | +| `superpowers:writing-plans` | Use during plan generation for structured planning | +| `superpowers:test-driven-development` | TDD-within-Blueprint: blueprint acceptance criteria become failing tests | +| `superpowers:verification-before-completion` | Use for gate validation in every phase | +| `superpowers:executing-plans` | Use during implementation phase | +| `superpowers:dispatching-parallel-agents` | Use for agent team coordination | + +--- + +## Quick Start + +### For a New Project (Greenfield) + +1. **Set up context directory:** + ``` + context/ + โ”œโ”€โ”€ refs/ # Source materials (PRDs, language specs, research) + โ”œโ”€โ”€ blueprints/ # Implementation-agnostic blueprints + โ”œโ”€โ”€ plans/ # Framework-specific implementation plans + โ”œโ”€โ”€ impl/ # Living implementation tracking + โ””โ”€โ”€ prompts/ # DABI pipeline prompts + ``` + +2. **Write blueprints** from your reference materials (see `bp:blueprint-writing`) +3. **Generate plans** from blueprints (see `bp:prompt-pipeline`) +4. **Implement** with validation gates (see `bp:validation-first`) +5. **Track progress** in implementation documents (see `bp:impl-tracking`) +6. **Iterate** โ€” when gaps are found, revise blueprints (see `bp:revision`) + +### For an Existing Project (Brownfield) + +1. **Set up context directory** (same structure as above) +2. **Designate existing codebase as reference material** +3. **Generate blueprints from code** (see `blueprint:brownfield-adoption`) +4. **Validate blueprints match behavior** โ€” run tests against generated blueprints +5. **Proceed with normal DABI** โ€” future changes flow through blueprints first + +--- + +## Summary + +Blueprint is not a tool โ€” it is a methodology. The core loop is simple: + +1. **Describe what you want** (blueprints with testable criteria) +2. **Let agents build it** (plans โ†’ implementation โ†’ validation) +3. **Fix the blueprints, not the code** (revision) +4. **Repeat until converged** (iteration loops) + +Agents become more capable the more precisely you constrain them โ€” clear blueprints, automated validation, and structured iteration loops let them operate with increasing autonomy. None of this eliminates the need for software engineers. Your judgment on architecture, your ability to write precise blueprints, and your instinct for what "done" looks like are the inputs that make the whole system function. Blueprint is a force multiplier: one engineer's clarity of thought, scaled across an entire implementation pipeline. diff --git a/plugins/JuliusBrussee/blueprint/skills/peer-review-loop/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/peer-review-loop/SKILL.md new file mode 100644 index 0000000..613b1c2 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/peer-review-loop/SKILL.md @@ -0,0 +1,253 @@ +--- +name: peer-review-loop +description: > + Peer Review Ralph Loop โ€” combines Blueprint blueprints with a Ralph Loop and true cross-model peer review + using Codex (OpenAI). Claude builds from specs; Codex reviews adversarially. + Primary path: Codex CLI delegation via codex-review.sh (fast, no MCP overhead). + Legacy fallback: Codex as MCP server when CLI delegation is unavailable. + Covers setup, iteration patterns, convergence detection, and completion criteria. + Triggers: "peer review loop", "ralph loop with codex", "blueprint ralph", "peer review build loop", + "cross-model loop", "codex peer reviewer", "blueprint to ralph loop" +--- + +# Peer Review Loop โ€” Blueprint + Ralph Loop + Codex Peer reviewer + +Run a Blueprint blueprint through a Ralph Loop where Claude builds and Codex adversarially reviews. +This is the most rigorous automated quality process available: every few iterations, a completely +different model (different training data, different biases, different blind spots) challenges +your implementation. + +--- + +## Why This Works + +| Factor | Single-Model Loop | Peer Review Loop | +|--------|-------------------|------------------| +| Blind spots | Same model, same blind spots every iteration | Two models catch different classes of issues | +| Blueprint drift | Builder may silently deviate from blueprint | Peer reviewer checks blueprint compliance explicitly | +| Quality floor | Converges to "good enough for one model" | Converges to "survives cross-examination" | +| Dead ends | May retry failed approaches | Peer reviewer flags repeated patterns | + +--- + +## Architecture + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Ralph Loop โ”‚ +โ”‚ (Stop hook feeds same prompt each iteration) โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Claude โ”‚โ”€โ”€โ”€โ–ถโ”‚ Build from โ”‚โ”€โ”€โ”€โ–ถโ”‚ Commit โ”‚ โ”‚ +โ”‚ โ”‚ (Build) โ”‚ โ”‚ blueprint + โ”‚ โ”‚ changes โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ–ฒ โ”‚ โ”‚ +โ”‚ โ”‚ โ–ผ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Fix โ”‚โ—€โ”€โ”€โ”‚ Parse โ”‚โ—€โ”€โ”€โ”‚ Codex CLI โ”‚ โ”‚ +โ”‚ โ”‚ findings โ”‚ โ”‚ findings โ”‚ โ”‚ (Review) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ +โ”‚ Completion: all blueprint requirements met + โ”‚ +โ”‚ no CRITICAL/HIGH findings โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Review Invocation: Codex CLI (primary) vs MCP (legacy) + +The peer review loop supports two invocation paths: + +1. **Codex CLI delegation (primary)** โ€” Uses `scripts/codex-review.sh` which + calls `codex` directly in `--approval-mode full-auto` with a structured + review prompt. Faster, no MCP server overhead, findings are parsed and + appended to `context/impl/impl-review-findings.md` automatically. + +2. **MCP server (legacy fallback)** โ€” Configures Codex as an MCP server in + `.mcp.json`. Claude calls the MCP tool on review iterations. Used only when + Codex CLI delegation is unavailable (e.g., older Codex versions). + +The build script (`setup-build.sh`) auto-detects which path to use: if +`codex-review.sh` is present and `codex` CLI is available, it uses CLI +delegation. Otherwise it falls back to MCP configuration. + +--- + +## Quick Start + +```bash +# Basic: implement a blueprint with peer review +/bp:peer-review-loop context/blueprints/blueprint-auth.md + +# With options +/bp:peer-review-loop context/blueprints/blueprint-api.md --max-iterations 20 --codex-model gpt-5.4-mini + +# Review-only mode (review existing code, don't build new) +/bp:peer-review-loop context/blueprints/blueprint-api.md --review-only + +# Review every iteration instead of every 2nd +/bp:peer-review-loop context/blueprints/blueprint-auth.md --review-interval 1 +``` + +--- + +## What the Command Does + +1. **Validates** the blueprint file exists and Codex CLI is installed +2. **Configures** Codex as an MCP server in `.mcp.json` (if not already configured) +3. **Builds** a Ralph Loop prompt that embeds: + - The blueprint path and related plan/impl files + - Instructions to alternate between build and review iterations + - The peer review prompt template for Codex + - Completion criteria tied to blueprint acceptance criteria +4. **Starts** the Ralph Loop via the stop hook mechanism + +--- + +## Codex Review Invocation + +### Primary: Codex CLI via codex-review.sh + +When `codex` CLI is available, the loop delegates review to `scripts/codex-review.sh` +which exposes the `bp_codex_review` function. This runs Codex in `full-auto` mode with +a structured adversarial review prompt, parses findings into a standardized table, and +appends them to `context/impl/impl-review-findings.md`. + +```bash +# What the build loop runs on review iterations: +source scripts/codex-review.sh +bp_codex_review --base main +``` + +The CLI path is faster (no MCP server startup), produces structured findings with +severity levels (P0-P3), and handles fallback gracefully if Codex is unavailable. + +### Legacy fallback: Codex MCP Server + +When Codex CLI delegation is not available, the command configures Codex as an MCP +server automatically: + +```json +{ + "mcpServers": { + "codex-reviewer": { + "command": "codex", + "args": ["mcp-server", "-c", "model=\"gpt-5.4\""] + } + } +} +``` + +Claude calls this MCP server on review iterations to get peer review feedback. The MCP server +exposes Codex as a tool that accepts prompts and returns responses โ€” Claude sends the blueprint + +code diff, Codex returns findings. + +### Changing the Codex Model + +Use `--codex-model` to specify which OpenAI model Codex should use: + +```bash +/bp:peer-review-loop blueprint.md --codex-model gpt-5.4-mini # faster, cheaper +/bp:peer-review-loop blueprint.md --codex-model gpt-5.4 # default, most capable +``` + +--- + +## Iteration Pattern + +``` +Iteration 1: BUILD โ€” Read blueprint, implement first requirement +Iteration 2: REVIEW โ€” Call Codex CLI (or MCP fallback), get findings, fix CRITICAL/HIGH +Iteration 3: BUILD โ€” Continue implementing, address remaining findings +Iteration 4: REVIEW โ€” Call Codex CLI (or MCP fallback) again, new findings on new code +... +Iteration N: BUILD โ€” All requirements met, all findings fixed + โ†’ outputs SPEC COMPLETE +``` + +The review interval is configurable. Default is every 2nd iteration. +Use `--review-interval 1` for maximum rigor (review every iteration). + +--- + +## Peer Review Findings File + +Review findings are tracked in `context/peer-review-findings.md`: + +```markdown +# Peer Review Findings + +## Latest Review: Iteration 4 โ€” 2026-03-14T10:30:00Z +### Reviewer: Codex (gpt-5.4) + +| # | Severity | File | Issue | Status | +|---|----------|------|-------|--------| +| 1 | CRITICAL | src/auth.ts:L42 | Missing input validation on token | FIXED | +| 2 | HIGH | src/auth.ts:L67 | Race condition in session refresh | FIXED | +| 3 | MEDIUM | src/auth.ts:L15 | Unused import | NEW | +| 4 | LOW | src/auth.ts:L3 | Comment typo | WONTFIX | + +## History +### Iteration 2 +| # | Severity | File | Issue | Status | +|---|----------|------|-------|--------| +| 1 | CRITICAL | src/auth.ts:L20 | SQL injection in login query | FIXED | +``` + +--- + +## Completion Criteria + +The loop exits when the completion promise is output. The prompt instructs Claude +to ONLY output it when ALL of these are true: + +- All blueprint requirements (R-numbers) have been implemented +- All acceptance criteria pass +- No CRITICAL or HIGH peer review findings remain unfixed +- Build passes +- Tests pass +- At least one review iteration completed with no new CRITICAL/HIGH findings + +--- + +## Modes + +### Build + Review (default) +Alternates between implementing blueprint requirements and calling Codex for review. +Use for greenfield implementation from a blueprint. + +### Review Only (`--review-only`) +Skips building. Each iteration calls Codex to review existing code against the blueprint, +then fixes issues found. Use when code already exists and you want peer review QA. + +--- + +## Prerequisites + +1. **Codex CLI installed**: `npm install -g @openai/codex` +2. **OpenAI API key configured**: Codex needs authentication (via `codex login` or env var) +3. **Blueprint context directory**: Blueprint file must exist at the given path +4. **Ralph Loop plugin**: The ralph-loop plugin must be installed (provides the stop hook) + +--- + +## Convergence Signals + +The peer review loop has converged when: +- Codex's findings drop to zero or only LOW/MEDIUM severity +- Code diffs between iterations are minimal +- All blueprint requirements confirmed as met by both Claude and Codex + +If the loop hits max iterations without converging: +- Check `context/peer-review-findings.md` for persistent issues +- Consider whether the blueprint needs clarification +- Run `/bp:revise` to trace issues back to blueprints + +--- + +## Cross-References + +- **peer-review** โ€” The underlying peer review patterns and prompt templates +- **convergence-monitoring** โ€” How to detect convergence vs ceiling +- **validation-first** โ€” Validation gates that run on every build iteration +- **impl-tracking** โ€” How implementation progress is tracked across iterations +- **Ralph Loop** โ€” The underlying Ralph Loop mechanism diff --git a/plugins/JuliusBrussee/blueprint/skills/peer-review/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/peer-review/SKILL.md new file mode 100644 index 0000000..9e82dbd --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/peer-review/SKILL.md @@ -0,0 +1,433 @@ +--- +name: peer-review +description: > + Patterns for using a second AI agent or model to challenge the primary builder agent's work. + Covers six review modes (Diff Critique, Design Challenge, Threaded Debate, Delegated Scrutiny, + Deciding Vote, Coverage Audit), how to set up peer review with any model via MCP server, + peer review iteration loops that alternate builder and reviewer prompts, and prompt templates for + each strategy. The peer reviewer's job is to find what the builder missed, not to agree. + Triggers: "peer review", "peer review agent", "use another model to review", + "second opinion on code", "cross-model review". +--- + +# Peer Review + +Use a second AI agent to review and challenge the first agent's work. The peer reviewer exists to find +what the builder missed -- not to agree, not to be polite, and not to rubber-stamp. This is the +single most effective quality gate you can add beyond automated tests. + +## Core Principle + +> **The peer reviewer's job is to find what the builder missed, not to agree.** + +A review that says "looks good" is a wasted review. The peer review model should be given explicit +instructions to be critical, to challenge assumptions, and to look for what is *not* there rather +than what is. + +--- + +## Why Peer Review Works + +LLMs have blind spots. Every model has patterns it over-relies on, edge cases it misses, and +architectural assumptions it makes implicitly. A second model -- or the same model with a different +prompt and role -- catches a different set of issues. + +**The analogy:** In traditional engineering, code review exists because the author has cognitive +blind spots about their own work. The same principle applies to AI agents, but the blind spots are +different: they are systematic patterns in training data, context window limitations, and prompt +interpretation biases. + +**What peer review catches that automated tests miss:** +- Architectural over-engineering or under-engineering +- Missing error handling patterns +- Security vulnerabilities the builder didn't consider +- Blueprint requirements that were technically met but poorly implemented +- Dead code, unused imports, and unnecessary complexity +- Performance pitfalls that only manifest at scale +- Missing edge cases not covered by the blueprint + +--- + +## Review Modes + +| Mode | Timing | Mechanism | +|------|--------|-----------| +| **Diff Critique** | After implementation completes | A second model inspects the changeset with a fault-finding prompt; the builder incorporates valid fixes | +| **Design Challenge** | During the planning phase | A second model proposes alternative designs; the builder evaluates both against spec requirements and selects the stronger option | +| **Threaded Debate** | When exploring complex trade-offs | Multiple exchanges occur on a persistent conversation thread so context accumulates across turns | +| **Delegated Scrutiny** | For substantial review tasks | A dedicated teammate agent manages the full peer review interaction and delivers a consolidated findings report to the lead | +| **Deciding Vote** | When two approaches conflict | The lead presents both options to the peer review model, which analyzes trade-offs and recommends a path forward | +| **Coverage Audit** | During the validation phase | Test coverage data and gap analysis are fed to the peer review model for independent assessment of testing thoroughness | + +### Choosing the Right Mode + +``` +Need peer review +โ”œโ”€ Reviewing completed code? +โ”‚ โ”œโ”€ Small changeset (< 500 lines) โ†’ Diff Critique +โ”‚ โ””โ”€ Large changeset or full feature โ†’ Delegated Scrutiny +โ”œโ”€ Designing architecture? +โ”‚ โ”œโ”€ Single decision point โ†’ Deciding Vote +โ”‚ โ””โ”€ Full system design โ†’ Design Challenge +โ”œโ”€ Debating trade-offs? +โ”‚ โ”œโ”€ Need extended back-and-forth โ†’ Threaded Debate +โ”‚ โ””โ”€ Need a decisive answer โ†’ Deciding Vote +โ””โ”€ Validating test quality? + โ””โ”€ Coverage Audit +``` + +--- + +## Setting Up Peer Review via MCP Server + +Any AI model that exposes an MCP server interface can serve as an peer reviewer. The setup +is model-agnostic -- the pattern works with any model that supports the MCP protocol. + +### Generic MCP Configuration + +Add the peer review model as an MCP server in your project's `.mcp.json`: + +```json +{ + "mcpServers": { + "peer reviewer": { + "command": "{ADVERSARY_CLI}", + "args": ["mcp-server"], + "env": { + "API_KEY": "{ADVERSARY_API_KEY}" + } + } + } +} +``` + +Replace `{ADVERSARY_CLI}` with the CLI command for your chosen model (e.g., any model's CLI tool +that supports MCP server mode) and `{ADVERSARY_API_KEY}` with the appropriate credentials. + +### Two Core MCP Tools + +Most peer review model MCP servers expose two tools: + +1. **Start session** -- Begin a new conversation with the peer review model + - Parameters: prompt, approval policy, sandbox mode, model selection + - Returns: a thread/session identifier + +2. **Reply to session** -- Continue an existing conversation + - Parameters: thread/session ID, follow-up message + - Returns: the model's response + +The thread/session identifier is critical -- it allows multi-turn conversations where the peer reviewer +builds on previous context. + +### Example: Starting an Peer Review Session + +``` +Tool: peer reviewer.start_session +Parameters: + prompt: "Review the following code changes for bugs, security issues, + missing edge cases, and spec compliance. Be critical -- your + job is to find problems, not to agree. Here are the changes: + {DIFF_CONTENT}" + model: "{ADVERSARY_MODEL}" +``` + +### Example: Multi-Turn Follow-Up + +``` +Tool: peer reviewer.reply_to_session +Parameters: + thread_id: "{THREAD_ID_FROM_PREVIOUS}" + message: "Good findings. Now focus specifically on error handling paths. + For each function that can fail, verify there is explicit + error handling and that errors propagate correctly." +``` + +--- + +## Strategy Details + +### 1. Diff Critique + +**When:** After a builder agent completes implementation of a feature or fix. + +**Process:** +1. Builder agent implements the feature and commits +2. Generate a diff of all changes: `git diff {BASE_BRANCH}...HEAD` +3. Send the diff to the peer review model with a code review prompt +4. Parse the peer reviewer's findings into actionable items +5. Builder agent applies fixes for valid findings +6. Optionally: send fixes back to peer reviewer for re-review + +**Review Prompt Template:** +```markdown +You are a senior code reviewer. Review the following code changes critically. + +## What to look for: +- Bugs, logic errors, off-by-one errors +- Security vulnerabilities (injection, auth bypass, data exposure) +- Missing error handling and edge cases +- Performance issues (N+1 queries, unnecessary allocations, blocking calls) +- Blueprint compliance: does this implementation match the requirements? +- Code quality: naming, structure, unnecessary complexity + +## What NOT to do: +- Do not say "looks good" unless you genuinely found zero issues +- Do not suggest stylistic changes unless they affect readability significantly +- Do not rewrite the code -- describe the problem and where it is + +## Blueprint requirements for this feature: +{BLUEPRINT_REQUIREMENTS} + +## Code changes: +{DIFF_CONTENT} + +## Output format: +For each finding: +- **Severity:** CRITICAL / HIGH / MEDIUM / LOW +- **File:** path and line range +- **Issue:** what is wrong +- **Why:** why this matters +- **Suggestion:** how to fix it +``` + +### 2. Design Challenge + +**When:** During the planning phase, before implementation begins. + +**Process:** +1. Builder agent drafts an architecture or plan +2. Send the plan + blueprints to the peer review model +3. Peer reviewer proposes alternative approaches or critiques the plan +4. Builder validates both approaches against blueprints +5. Human makes the final decision if there is a genuine trade-off + +**Architecture Review Prompt Template:** +```markdown +You are a systems architect reviewing a proposed design. Your goal is to +find weaknesses, over-engineering, missing considerations, and better +alternatives. + +## Blueprints (what must be built): +{BLUEPRINT_CONTENT} + +## Proposed architecture: +{PLAN_CONTENT} + +## Evaluate: +1. Does this architecture satisfy all blueprint requirements? +2. Is it over-engineered for the scope? +3. Are there simpler alternatives that meet the same requirements? +4. What failure modes exist? How does the system recover? +5. What are the scaling bottlenecks? +6. What dependencies introduce risk? +``` + +### 3. Threaded Debate + +**When:** Complex design discussions that require extended back-and-forth. + +**Process:** +1. Start a session with the peer review model presenting the problem +2. Use reply-to-session to continue the conversation across multiple turns +3. Maintain the thread ID throughout the discussion +4. Summarize conclusions when the discussion converges + +**Key consideration:** Thread-based conversations accumulate context. Keep the +conversation focused on a single topic to avoid context dilution. + +### 4. Delegated Scrutiny + +**When:** Large tasks where the peer review itself is substantial. + +**Process:** +1. Team lead spawns a teammate specifically for peer review coordination +2. The teammate owns the peer reviewer MCP interaction +3. Teammate manages multi-turn review sessions +4. Teammate summarizes findings and reports to the team lead +5. Team lead assigns fixes to the appropriate builder teammates + +**Why delegate:** The peer review back-and-forth can consume significant context +window. Delegating it to a dedicated teammate preserves the team lead's context +for coordination. + +### 5. Deciding Vote + +**When:** The builder agent and human (or two agents) disagree on an approach. + +**Process:** +1. Present both perspectives to the peer review model +2. Ask it to evaluate the trade-offs of each approach +3. Ask it to recommend one, with explicit reasoning +4. Use the recommendation to inform the decision (human has final say) + +**Tie-Breaking Prompt Template:** +```markdown +Two approaches have been proposed for the same problem. Evaluate both +critically and recommend one. + +## Context: +{PROBLEM_DESCRIPTION} + +## Approach A: +{APPROACH_A} + +## Approach B: +{APPROACH_B} + +## Evaluation criteria: +- Correctness: which approach is more likely to be correct? +- Simplicity: which is easier to understand and maintain? +- Performance: which performs better for the expected use case? +- Risk: which has fewer failure modes? + +## Your recommendation: +Pick one and explain why. If neither is clearly better, say so and +explain what additional information would break the tie. +``` + +### 6. Coverage Audit + +**When:** During validation, after tests have been generated and run. + +**Process:** +1. Run test coverage analysis on the codebase +2. Generate a coverage report (which files/functions are covered) +3. Send the coverage report + blueprints to the peer review model +4. Peer reviewer identifies: untested edge cases, missing integration tests, + blueprint requirements without corresponding tests +5. Builder adds missing tests + +--- + +## Peer Review Iteration (Convergence Loop with Review) + +Instead of a simple build-then-review, run alternating convergence loops where each +iteration alternates between building and reviewing. + +### The Pattern + +``` +Iteration 1: Builder runs against spec โ†’ produces code +Iteration 2: Reviewer runs against code + spec โ†’ produces findings +Iteration 3: Builder runs against spec + findings โ†’ fixes code +Iteration 4: Reviewer runs against updated code + spec โ†’ produces new findings +...repeat until findings converge to zero (or trivial) +``` + +### Implementation with Separate Prompts + +Create two prompt files: + +**`prompts/build.md`** -- The builder prompt: +```markdown +Implement the requirements in the blueprint. Read implementation tracking for +context on what has been done. Read any review findings and address them. + +Input: blueprints/, plans/, impl/, review-findings.md (if exists) +Output: source code, updated impl tracking +Exit: all blueprint requirements implemented, all review findings addressed +``` + +**`prompts/review.md`** -- The reviewer prompt: +```markdown +Review the current implementation against the blueprint. Be critical. Find +bugs, missing requirements, security issues, and quality problems. + +Input: blueprints/, plans/, source code, impl/ +Output: review-findings.md +Exit: all source files reviewed against all blueprint requirements +``` + +### Running Peer Review Iteration + +```bash +# Terminal 1: Builder convergence loop +{LOOP_TOOL} prompts/build.md -n 5 -t 2h + +# Terminal 2: Reviewer convergence loop (staggered by 30 min) +{LOOP_TOOL} prompts/review.md -n 5 -t 2h -d 30m +``` + +The builder and reviewer share the same git repository. The reviewer reads the +builder's latest committed code; the builder reads the reviewer's latest +`review-findings.md`. They converge naturally through git. + +### Convergence Signal + +The peer review loop has converged when: +- The reviewer's findings drop to zero or only LOW severity items remain +- The builder's diffs between iterations are minimal +- All blueprint requirements have been reviewed and confirmed as met + +--- + +## Anti-Patterns + +### 1. Peer reviewer as Yes-Man +**Problem:** The peer review model says "looks good" without finding real issues. +**Fix:** Explicitly instruct the peer reviewer to find problems. Add to the prompt: +"If you find zero issues, explain what areas you checked and why you believe +they are correct. An empty review is suspicious." + +### 2. Peer reviewer Rewrites Everything +**Problem:** The peer reviewer provides complete rewrites instead of identifying issues. +**Fix:** Instruct the peer reviewer to describe problems and locations, not to write +code. "Your output is a list of findings, not a pull request." + +### 3. Builder Ignores Findings +**Problem:** The builder agent dismisses peer reviewer findings without addressing them. +**Fix:** Require the builder to explicitly respond to each finding: "For each +review finding, either fix it and explain the fix, or explain why the finding +is not valid. You may not skip any finding." + +### 4. Infinite Disagreement Loop +**Problem:** Builder and reviewer keep going back and forth without converging. +**Fix:** Set a maximum iteration count. After N iterations, escalate to human. +If the disagreement persists, it likely indicates an ambiguous spec that needs +human clarification. + +### 5. Same Model Reviewing Itself +**Problem:** Using the same model with the same prompt for both building and reviewing. +**Fix:** At minimum, use different prompts with different roles. Ideally, use a +different model or a different model version. The value of peer review comes +from diverse perspectives. + +--- + +## Prompt Templates Quick Reference + +| Mode | Key Prompt Instruction | +|------|----------------------| +| Diff Critique | "Find bugs, security issues, missing edge cases. Do not say 'looks good'." | +| Design Challenge | "Find weaknesses and simpler alternatives. Evaluate failure modes." | +| Threaded Debate | "Continue the discussion. Build on previous context." | +| Delegated Scrutiny | "Own the peer reviewer interaction. Summarize findings for the lead." | +| Deciding Vote | "Evaluate both approaches. Recommend one with explicit reasoning." | +| Coverage Audit | "Identify untested edge cases and spec requirements without tests." | + +--- + +## Integration with Blueprint Lifecycle + +Peer review fits into the DABI lifecycle at multiple points: + +| DABI Phase | Peer Review Role | +|-------------|-----------------| +| **Draft** | Review blueprints for completeness, ambiguity, missing edge cases | +| **Architect** | Architecture Review: challenge the plan before implementation begins | +| **Build** | Code Review: review implementation against blueprints after each feature | +| **Inspect** | Peer Review iteration loop: alternate build/review convergence | +| **Monitor** | Test Coverage Review: validate that monitoring covers all failure modes | + +The most impactful point is during **Inspect** -- peer review iteration catches issues +that neither automated tests nor single-agent convergence loops find. + +--- + +## Cross-References + +- **convergence-monitoring** -- How to detect when peer review iterations have converged +- **validation-first** -- Peer review is Gate 6 (human/agent review) in the validation pipeline +- **prompt-pipeline** -- How to structure builder and reviewer prompts in the DABI pipeline +- **revision** -- When the peer reviewer finds a blueprint gap, revise the fix into blueprints +- **impl-tracking** -- Record peer review findings in implementation tracking documents diff --git a/plugins/JuliusBrussee/blueprint/skills/prompt-pipeline/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/prompt-pipeline/SKILL.md new file mode 100644 index 0000000..4120341 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/prompt-pipeline/SKILL.md @@ -0,0 +1,451 @@ +--- +name: prompt-pipeline +description: > + How to design the numbered prompt pipeline that drives DABI phases in Blueprint. + Covers greenfield 3-prompt patterns, rewrite 6-9 prompt patterns, shared principles, + prompt engineering best practices, task templates, and time guards. + Trigger phrases: "prompt pipeline", "design prompts for SDD", "create DABI prompts", + "pipeline prompts", "how many prompts do I need" +--- + +# Prompt Pipeline Design + +The prompt pipeline is the engine of SDD. Each numbered prompt drives one phase of the DABI lifecycle (Spec, Plan, Implement, Iterate, Monitor). Prompts are structured markdown files that instruct an AI agent to perform a specific phase, with detailed information delegated to specs, plans, and reference materials. + +**Core principle:** Prompts should be as lightweight and systemic as possible. They define the *process*, not the *content* -- specs and plans hold the content. + +--- + +## 1. Greenfield Pattern (3-Prompt Pipeline) + +For new projects starting from reference materials (PRDs, language specs, design docs, research). + +``` +Pipeline Flow: + refs/ โ”€โ”€> [001] โ”€โ”€> specs/ โ”€โ”€> [002] โ”€โ”€> plans/ โ”€โ”€> [003] โ”€โ”€> src/ + tests/ + ^ | + | | + +โ”€โ”€ impl/ <โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€+ + (bidirectional flow) +``` + +| Prompt File | Lifecycle Stage | Reads From | Writes To | Description | +|-------------|----------------|------------|-----------|-------------| +| `001-generate-specs-from-refs.md` | **Spec** | `context/refs/` | `context/blueprints/` | Reads reference materials, decomposes into domain-specific specs with cross-references and testable acceptance criteria | +| `002-generate-plans-from-specs.md` | **Plan** | `context/blueprints/` + `context/impl/` | `context/plans/` | Reads specs plus implementation progress, creates framework-specific plans with feature dependencies, test strategies, and acceptance criteria | +| `003-generate-impl-from-plans.md` | **Implement** | `context/plans/` + `context/blueprints/` | `src/`, `tests/`, `context/impl/` | Implements the highest-priority unblocked work from plans, runs tests, updates implementation tracking | + +### Key behaviors + +- **Prompt 001** runs once or a few times to stabilize specs. It reads `context/refs/` and produces `context/blueprints/`. +- **Prompt 002** reads specs and any existing implementation tracking (`context/impl/`). It produces plans that sequence the work. +- **Prompt 003** reads plans and specs, implements code, runs validation gates, and updates `context/impl/` with progress. +- **Prompts 002 and 003 modify each other's files.** This bidirectional flow is expected and healthy -- it is how the system self-corrects. + +### Example prompt 001 structure + +```markdown +# 001: Generate Specs from Reference Materials + +## Runtime Inputs +- Framework: {FRAMEWORK} +- Build command: {BUILD_COMMAND} +- Test command: {TEST_COMMAND} + +## Context +Read all files in `context/refs/`. These are the source of truth. + +## Task +Decompose the reference materials into domain-specific specifications: +1. Create `context/blueprints/blueprint-overview.md` as the index file +2. Create one `context/blueprints/spec-{domain}.md` per domain +3. Each spec must include: Scope, Requirements with Acceptance Criteria, Dependencies, Out of Scope, Cross-References + +## Exit Criteria +- [ ] All domains from reference materials have corresponding spec files +- [ ] Every requirement has at least one testable acceptance criterion +- [ ] blueprint-overview.md indexes all spec files with one-line summaries +- [ ] Cross-references link related specs + +## Completion Signal + +``` + +--- + +## 2. Rewrite Pattern (6-9 Prompt Pipeline) + +For projects that start from existing code that must be reverse-engineered into specs before building a new implementation. + +``` +Pipeline Flow: + old-code โ”€โ”€> [001] โ”€โ”€> reference/ โ”€โ”€> [002] โ”€โ”€> specs/ โ”€โ”€> [003] โ”€โ”€> validated specs + | + +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€+ + | + v + specs/ โ”€โ”€> [004] โ”€โ”€> plans/ โ”€โ”€> [005] โ”€โ”€> src/ + tests/ โ”€โ”€> [006] โ”€โ”€> updated specs + | + +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€+ + | + v + (loop back to 002 for refinement) +``` + +| Prompt File | Lifecycle Stage | Reads From | Writes To | +|-------------|----------------|------------|-----------| +| `001-generate-refs-from-code.md` | Pre-Spec | Old application source | `shared-context/reference/` (API docs, data models, UI components) | +| `002-generate-specs.md` | Spec | Feature scope + reference materials | `shared-context/blueprints/` (implementation-agnostic specs) | +| `003-validate-specs.md` | Spec QA | Reference + specs | Validation report (specs match old behavior) | +| `004-create-plans.md` | Plan | Specs + framework research | `context/plans/` (framework-specific plans) | +| `005-implement.md` | Implement | Plans + specs | `src/` + `tests/` + `context/impl/` | +| `006-backpropagate.md` | Iterate | Working prototype | Updated specs (back-propagates to 002) | + +### Rewrite-specific considerations + +- **Prompt 001** only runs once -- it extracts reference documentation from the old codebase. +- **Prompt 003** is a validation pass -- it does not produce code, only a report on spec accuracy. +- **Prompt 006** creates a feedback loop: prototype learnings flow back into specs, which then flow forward through 004 and 005 again. +- The rewrite pipeline supports **multi-repo strategies**: shared specs can drive implementations in multiple frameworks simultaneously (e.g., evaluating framework A vs framework B using the same specs). + +--- + +## 3. Shared Principles Across All Pipelines + +These principles apply regardless of whether the pipeline is greenfield, rewrite, or hybrid. + +| Principle | Detail | +|-----------|--------| +| **One prompt per DABI phase** | Each prompt maps to exactly one phase. Do not combine phases. | +| **Explicit input/output directories** | Every prompt declares what it reads and what it writes. No implicit side effects. | +| **Git-based continuity** | Agents read git history (`git log`, `git diff`, `git status`) between iterations to understand what was done before. | +| **Explicit done-conditions with termination markers** | Every prompt concludes with a verifiable checklist of conditions and a distinct output token that the iteration loop uses to detect completion. | +| **Bidirectional spec/plan updates** | Plan prompts read impl tracking; implement prompts update plans. This cross-pollination is healthy. | +| **Test generation on changed files** | After modifying source files, run test generation to maintain coverage. | +| **Phase gates between prompts** | Before moving to the next prompt, verify: build passes, tests pass, acceptance criteria met. | + +### The bidirectional flow in detail + +``` +Prompt 002 (Plans): + READS: context/blueprints/ (what to build) + READS: context/impl/ (what has been built, what failed) + WRITES: context/plans/ (how to build it) + +Prompt 003 (Implement): + READS: context/plans/ (how to build it) + READS: context/blueprints/ (acceptance criteria) + WRITES: src/, tests/ (the code) + WRITES: context/impl/ (progress tracking) + WRITES: context/plans/ (updates to plans based on implementation reality) +``` + +This means running prompt 002 again after prompt 003 will incorporate implementation learnings into plans. Running prompt 003 again after prompt 002 will implement updated plans. This is exactly the convergence loop at work. + +--- + +## 4. Prompt Engineering Best Practices + +### 4.1 Runtime Inputs + +Use runtime variables so prompts work across any project without modification: + +```markdown +## Runtime Inputs +- Framework: {FRAMEWORK} # e.g., "React + Vite", "Tauri + Svelte" +- Build command: {BUILD_COMMAND} # e.g., "npm run build", "cargo build" +- Test command: {TEST_COMMAND} # e.g., "npm test", "pytest" +- Lint command: {LINT_COMMAND} # e.g., "npm run lint", "cargo clippy" +- Source dir: {SRC_DIR} # e.g., "src/", "lib/" +- Test dir: {TEST_DIR} # e.g., "tests/", "__tests__/" +``` + +### 4.2 Agent Team Structure (ASCII Trees) + +When prompts use agent teams, define the hierarchy explicitly as an ASCII tree: + +``` +Agent Team Structure: + Lead (delegate mode -- never writes code directly) + +-- Teammate A: domain-auth + | Owns: src/auth/*, context/impl/impl-auth.md + | Dispatch: Agent tool with isolation: "worktree" + +-- Teammate B: domain-data + | Owns: src/data/*, context/impl/impl-data.md + | Dispatch: Agent tool with isolation: "worktree" + +-- Teammate C: domain-ui + Owns: src/ui/*, context/impl/impl-ui.md + Dispatch: Agent tool with isolation: "worktree" +``` + +**Why:** Agents need to understand their role and what they own. Dispatch subagents with `isolation: "worktree"` via the Agent tool for filesystem isolation. After merging a subagent's branch, the caller must clean up: `git worktree remove ` then `git branch -D `. Claude Code only auto-cleans worktrees when agents make no changes. + +### 4.3 Batching Rules + +- **Max 3 concurrent teammates** per batch. Prevents resource exhaustion and race conditions. +- **Batch phases:** Spawn batch 1 (3 teammates) -> wait for completion -> shutdown -> spawn batch 2. +- **Max 3 sub-agents per teammate.** Sub-agents handle discrete subtasks (reading docs, running tests) to preserve the teammate's context window. + +``` +Execution Timeline: + Batch 1: [Teammate A] [Teammate B] [Teammate C] + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€> complete, shutdown + Batch 2: [Teammate D] [Teammate E] [Teammate F] + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€> complete, shutdown +``` + +### 4.4 File Ownership Tables + +Assign each shared file to exactly one teammate to eliminate merge conflicts: + +```markdown +## File Ownership +| File/Pattern | Owner | +|-------------|-------| +| `src/auth/**` | domain-auth | +| `src/data/**` | domain-data | +| `src/ui/**` | domain-ui | +| `src/shared/types.ts` | domain-data | +| `context/impl/impl-auth.md` | domain-auth | +``` + +**Rule:** If two teammates need to modify the same file, assign ownership to one and have the other request changes through the lead. + +### 4.5 Exit Criteria and Completion Signals + +Every prompt must end with explicit exit criteria and a completion signal: + +```markdown +## Exit Criteria +- [ ] All T- tasks are DONE or documented as BLOCKED +- [ ] {BUILD_COMMAND} passes with zero errors +- [ ] {TEST_COMMAND} passes with zero failures +- [ ] All modified source files have corresponding test coverage +- [ ] context/impl/ updated with current status + +## Completion Signal +When ALL exit criteria are met, output exactly: + + +This signal is used by the iteration loop to detect when to stop. +``` + +### 4.6 Spawn Templates + +Teammates are fresh processes with **no inherited history**. Every spawn must include full context: + +```markdown +## Spawn Template for Teammate + +You are implementing {DOMAIN} for the {PROJECT_NAME} project. + +### Your Role +- You own: {FILE_PATTERNS} +- Isolation: dispatched via Agent tool with `isolation: "worktree"` +- Your impl tracking: context/impl/impl-{DOMAIN}.md + +### Context to Read First +1. context/blueprints/spec-{DOMAIN}.md (WHAT to build) +2. context/plans/plan-{DOMAIN}.md (HOW to build it) +3. context/impl/impl-{DOMAIN}.md (what has been done) +4. git log --oneline -20 (recent history) + +### Task +{TASK_DESCRIPTION} + +### Exit Criteria +- [ ] {CRITERIA} + +### Halting Conditions +- Do NOT push to remote unless explicitly asked +- Do NOT modify files outside your ownership +- If blocked for more than 20 minutes, document the blocker and stop +``` + +### 4.7 Halting Conditions + +Explicit halting conditions prevent irreversible or wasteful actions: + +```markdown +## Halting Conditions +- Do NOT push to remote unless explicitly asked +- Do NOT modify files outside your file ownership table +- Do NOT delete test files or skip failing tests +- If a task takes more than 20 minutes, document findings and move on +- If you encounter a circular dependency, document it and stop +- Commit frequently to preserve progress +``` + +### 4.8 Sub-Agent Delegation + +Teammates should delegate discrete subtasks to sub-agents to preserve their own context window: + +```markdown +## When to Use Sub-Agents +- Reading large documentation files +- Running and parsing test output +- Generating boilerplate code +- Researching framework APIs +- Performing file-by-file migrations + +## Sub-Agent Rules +- Max 3 concurrent sub-agents per teammate +- Each sub-agent gets a focused, self-contained task +- Sub-agent results are summarized back to the teammate +- Sub-agents do NOT inherit the teammate's conversation history +``` + +--- + +## 5. Task Template Standardization + +Use standardized task templates for consistent tracking across prompts: + +### Task ID format + +```markdown +### T-{DOMAIN}-{NUMBER}: {Task Title} +- **Status:** TODO | IN_PROGRESS | DONE | BLOCKED +- **blockedBy:** T-{OTHER_DOMAIN}-{NUMBER} (if applicable) +- **Files:** {list of files to create or modify} +- **Acceptance criteria:** + - [ ] {criterion 1} + - [ ] {criterion 2} +``` + +### Dependency tracking with blockedBy + +```markdown +### T-AUTH-001: Implement login flow +- **Status:** TODO +- **blockedBy:** T-DATA-001 (needs user model) + +### T-DATA-001: Create user data model +- **Status:** IN_PROGRESS +- **blockedBy:** none +``` + +### Conditional and dynamic tasks + +```markdown +### T-UI-005: Implement dark mode [CONDITIONAL] +- **Skip if:** {FRAMEWORK} does not support CSS variables +- **Status:** TODO + +### T-PERF-001: Optimize hot paths [DYNAMIC] +- **Created when:** Performance gate identifies bottlenecks +- **Status:** not yet created +``` + +**`[CONDITIONAL]`** tasks include a skip condition -- if the condition is met, the task is skipped without failure. + +**`[DYNAMIC]`** tasks are placeholders created at runtime when a specific trigger occurs. They do not exist in the initial plan. + +--- + +## 6. Time Guards + +Per-task time budgets prevent agents from spending too long on any single task: + +| Category | Budget | Examples | +|----------|--------|----------| +| **Mechanical** | 10 minutes | File creation, boilerplate, simple refactors | +| **Investigation** | 20 minutes | Debugging, researching APIs, understanding existing code | +| **Category budget** | 20 minutes | Total time for all tasks in one category before escalating | + +### Time guard rules + +1. **Set expectations in the prompt:** + ```markdown + ## Time Guards + - Mechanical tasks (file creation, boilerplate): 10 min max + - Investigation tasks (debugging, research): 20 min max + - If you hit a time guard, document your findings and move to the next task + - Do NOT silently retry -- document the blocker + ``` + +2. **Hard stops:** When a time guard is hit, the agent must: + - Document what was attempted + - Document what was learned + - Document the blocker or open question + - Move to the next unblocked task + +3. **Escalation:** If an agent hits time guards on multiple related tasks, this signals a systemic issue (fuzzy spec, missing dependency, architectural problem). Document it as a pattern, not individual failures. + +--- + +## 7. Prompt File Naming Convention + +``` +context/prompts/ ++-- 000-generate-specs-from-code.md # Brownfield only (bootstrap, runs once) ++-- 001-generate-specs-from-refs.md # Greenfield spec generation ++-- 002-generate-plans-from-specs.md # Plan generation ++-- 003-generate-impl-from-plans.md # Implementation ++-- 004-validate-specs.md # Spec validation (rewrite pipelines) ++-- 005-backpropagate.md # Back-propagation (rewrite pipelines) +``` + +### Naming rules + +- **Three-digit prefix** for ordering (000, 001, 002...) +- **Verb-noun format** describing the transformation (generate-specs-from-refs) +- **Lower prompt numbers** are upstream (closer to specs) +- **Higher prompt numbers** are downstream (closer to code) +- **000** is reserved for brownfield bootstrap (runs once, not in the main loop) + +--- + +## 8. Designing Your Pipeline + +### Step-by-step process + +1. **Identify your project type:** Greenfield (start from refs) or Rewrite (start from old code)? +2. **Start with the minimum pipeline:** Greenfield = 3 prompts. Rewrite = 6 prompts. +3. **Write prompt 001 first:** This is always the spec generation step. +4. **Define your runtime variables:** What framework, build command, test command? +5. **Set exit criteria for each prompt:** What must be true before moving to the next phase? +6. **Add agent teams if needed:** For large projects, add team structure and file ownership. +7. **Run the pipeline with the iteration loop:** Start with a small number of iterations (3-5) and increase as needed. +8. **Watch for convergence:** Exponentially decreasing changes = convergence. Flat or oscillating changes = fix your specs. + +### When to add more prompts + +- If a single prompt is trying to do too much (reading AND writing specs, for example), split it. +- If you see a phase producing inconsistent results, add a validation prompt between phases. +- If back-propagation is frequent, add an explicit back-propagation prompt (006 in the rewrite pattern). + +--- + +## 9. Iteration Loop Integration + +Prompts are designed to run inside an iteration loop that repeats them until convergence: + +```bash +# Greenfield: Run implementation prompt with iteration loop +# -n 10: max 10 iterations +# -t 1h: 1 hour timeout per iteration +iteration-loop context/prompts/003-generate-impl-from-plans.md -n 10 -t 1h + +# Leader-follower pattern: staggered pipeline +# Terminal 1: Specs (leader) +iteration-loop context/prompts/001-generate-specs-from-refs.md -n 5 -t 2h + +# Terminal 2: Plans (follower, 1h delay) +iteration-loop context/prompts/002-generate-plans-from-specs.md -n 5 -t 2h -d 1h + +# Terminal 3: Implementation (follower, 2h delay) +iteration-loop context/prompts/003-generate-impl-from-plans.md -n 10 -t 1h -d 2h +``` + +The iteration loop handles: iteration counting, timeouts, nudging idle agents, detecting completion signals, and graceful stop on convergence. + +--- + +## Cross-References + +- **Prompt engineering details:** See `references/prompt-engineering.md` for the complete reference on runtime inputs, spawn templates, task templates, time guards, and file ownership. +- **Agent team patterns:** See `references/agent-team-patterns.md` for coordination patterns, batching, agent isolation, and merge protocol. +- **Convergence monitoring:** See `bp:convergence-monitoring` skill for detecting when the iteration loop should stop. +- **Revision:** See `bp:revision` skill for how prompt 006 traces bugs back to specs. +- **Context architecture:** See `bp:context-architecture` skill for the directory structure that prompts read from and write to. diff --git a/plugins/JuliusBrussee/blueprint/skills/revision/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/revision/SKILL.md new file mode 100644 index 0000000..236aecd --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/revision/SKILL.md @@ -0,0 +1,342 @@ +--- +name: revision +description: > + The technique of tracing bugs and manual fixes back to blueprints and prompts, then fixing at the source + so the iteration loop can reproduce the fix autonomously. Covers the 6-step revision process, + commit classification, blueprint-level root cause analysis, and regression test generation. + Trigger phrases: "revise", "revision", "trace bug to blueprint", "fix the blueprint not the code", + "why did this bug happen", "update blueprints from bug" +--- + +# Revision: Tracing Bugs Back to Blueprints + +In Blueprint, revision means tracing a production defect upstream through the blueprint chain until you find the gap that allowed it. In practice, when the built software has bugs or gaps, you trace the issue back to the blueprints and prompts and fix at the source -- not just in code. + +**Key insight:** When a fix lives only in code with no corresponding blueprint update, the next iteration loop may reintroduce the same defect. The goal is that blueprints plus the iteration loop can reproduce any fix autonomously. + +--- + +## 1. Why Revision Matters + +Without revision, every bug fix is a one-off patch. The next time the iteration loop runs, it may reintroduce the bug because nothing in the blueprints or plans prevents it. + +With revision: +- Bug fixes become **blueprint improvements** that persist across all future iterations +- The iteration loop becomes **self-correcting** -- it learns from every manual intervention +- Blueprints become **progressively more complete** over time +- The gap between "what blueprints describe" and "what works" **shrinks monotonically** + +``` +Without revision: + Bug found -> Fix code -> Bug may return next iteration + +With revision: + Bug found -> Fix code -> Update blueprint -> Re-run iteration loop -> Fix emerges from blueprints alone +``` + +--- + +## 2. The 6-Step Revision Process + +This is the complete process for tracing a bug back to its blueprint-level root cause and closing the loop. + +### Step 1: Identify and Fix the Defect + +Locate the bug -- whether through manual testing, automated failures, user reports, or monitoring alerts -- and resolve it through normal debugging. This produces a working code change, but the job is far from done: until the underlying blueprint gap is closed, this fix is fragile. + +```bash +# The fix produces commits that we will analyze +git log --oneline -5 +# a1b2c3d Fix: connection pool exhaustion under concurrent load +# e4f5g6h Fix: missing rate limit headers in API responses +``` + +### Step 2: Analyze What the Blueprint Missed + +This is the pivotal step. Ask: **"Where in the blueprint chain did this requirement slip through?"** + +Break the analysis into five dimensions: +- **WHAT** changed (files, functions, observable behavior) +- **WHY** it was wrong (which assumption proved false) +- **VISUAL** โ€” does this fix change visual appearance (CSS, styling, layout)? If yes, check whether DESIGN.md covers the pattern. A missing design pattern is a design system gap that should be fixed alongside the blueprint gap. +- **The RULE** (the invariant that should have been stated) +- **The LAYER** (which blueprint, plan, or prompt should have contained this) + +Example analysis: + +```markdown +## Revision Analysis: Database Connection Pooling + +**WHAT changed:** Added pool size limits and idle timeout in `src/db/pool.ts` +**WHY:** The data layer blueprint assumed unlimited connections; under load the database + rejected new connections once the server-side limit was reached +**RULE:** "The database module MUST configure a bounded connection pool with + idle timeout and max-connection limits matching the deployment target" +**LAYER:** blueprint-data.md (no mention of pool configuration), plan-data.md (no task for pool tuning) +**Blueprint implications:** Add requirement R5 to blueprint-data.md covering connection pool settings +``` + +### Step 3: Update the Blueprint + +Add the missing requirement or constraint to the appropriate blueprint file. Focus on acceptance criteria that are concrete enough for the iteration loop to act on: + +```markdown +# In context/blueprints/blueprint-data.md, add: + +### R5: Database Connection Pool Configuration +**Description:** The database module must use a bounded connection pool +with configurable limits to prevent resource exhaustion under load. +**Acceptance Criteria:** +- [ ] Maximum pool size is configurable and defaults to a sensible value +- [ ] Idle connections are reaped after a configurable timeout +- [ ] Pool exhaustion returns a clear error rather than hanging indefinitely +- [ ] Connection health checks run before returning a connection from the pool +**Dependencies:** R1 (database client setup), R2 (environment configuration) +``` + +### Step 4: Propagate Changes to Plans and Tracking + +Trace the blueprint update through every downstream context file: + +1. **Identify affected plan files:** Which plans govern the changed source paths? +2. **Update plans:** Add or close tasks reflecting the new requirement. +3. **Update impl tracking:** Record the revision event and its root cause. +4. **Annotate:** Mark updated sections with revision metadata so future reviews can trace lineage. + +```markdown +# In context/plans/plan-data.md, add: + +### T-DATA-005: Configure bounded connection pool +- **Status:** DONE (revised from manual fix a1b2c3d) +- **Blueprint:** R5 in blueprint-data.md +- **Files:** src/db/pool.ts +- **Acceptance criteria:** + - [ ] Max pool size enforced + - [ ] Idle timeout configured + - [ ] Exhaustion handled gracefully +``` + +### Step 5: Apply Systemic Prompt Improvements (If Pattern Detected) + +When the defect represents a recurring class of problem rather than a one-off, elevate the fix to the prompt level so it applies across all domains: + +**Signs you are looking at a pattern:** +- The same category of bug has surfaced in more than one module +- The gap is structural (e.g., no specs anywhere address resource limits) +- A missing validation gate allowed the issue through + +**Example systemic fix:** + +```markdown +# In prompt 003, add to the validation section: + +## Resource Management Validation +For every external resource integration, verify: +- [ ] Connection or handle limits are bounded and configurable +- [ ] Idle resources are cleaned up on a timeout +- [ ] Exhaustion scenarios return actionable errors +- [ ] Resource lifecycle is covered by tests under load +``` + +### Step 6: Verify and Lock In + +Run the iteration loop against the updated blueprints to prove the fix emerges from blueprints alone, then generate regression tests to prevent future recurrence: + +```bash +# Proof step: remove the manual fix and re-run from specs +git stash # temporarily remove the manual fix +iteration-loop context/prompts/003-generate-impl-from-plans.md -n 5 -t 1h +# Verify the fix appears in the generated implementation + +# If it does NOT, the blueprint update is insufficient -- return to Step 3 +``` + +Once verified, create regression tests: + +```bash +# Generate tests targeting the updated blueprint +{TEST_COMMAND} --blueprint context/blueprints/blueprint-data.md + +# Or manually create a regression test +# tests/db/connection-pool-limits.test.ts +``` + +The regression tests should: +- Map directly to the acceptance criteria from Step 3 +- Fail if the fix is reverted +- Run as part of the standard test suite going forward + +--- + +## 3. Revision Analysis (Automated) + +The revision analysis automates Steps 2-4 by examining recent git history. + +### 3.1 Classify Commits + +Analyze recent commits and classify each as: + +| Classification | Meaning | Action | +|---------------|---------|--------| +| **Manual fix** | Human or interactive agent fixed a bug | Trace back to blueprint -- this is a revision target | +| **Iteration loop** | Automated iteration loop made the change | No action -- this is the system working as intended | +| **Infrastructure** | Build config, CI, tooling changes | No action -- not blueprint-related | + +**How to classify:** +- Commits from iteration loop sessions have predictable patterns (automated commit messages, batch changes) +- Manual fixes are typically single-issue, focused commits with descriptive messages +- Infrastructure changes touch config files, build scripts, CI pipelines + +### 3.2 Analyze Each Manual Fix + +For each commit classified as a manual fix, determine: + +```markdown +## Commit: abc1234 "Fix: auth token not refreshing on 401" + +### WHAT changed +- File: src/auth/client.ts +- Function: handleApiResponse() +- Behavior: Added 401 detection and token refresh logic + +### WHY it was wrong +- The auth module did not handle 401 responses +- Tokens would expire and never refresh, causing cascading auth failures + +### RULE (invariant that should have been specified) +- "Authentication tokens must be refreshed automatically on 401 responses" + +### LAYER (which context file should have caught this) +- blueprint-auth.md: Missing requirement for error-based token refresh +- plan-auth.md: No task for 401 handling + +### Blueprint Implications +- Add R7 to blueprint-auth.md: Token Refresh on Authentication Failure +- Add T-AUTH-007 to plan-auth.md: Implement token refresh on 401 +``` + +### 3.3 Discover Affected Plan Files + +Dynamically discover which plan files govern the changed source paths: + +``` +Changed file: src/auth/client.ts + -> Matches pattern: src/auth/* + -> Governed by: plan-auth.md + -> Blueprint: blueprint-auth.md + +Changed file: src/data/api.ts + -> Matches pattern: src/data/* + -> Governed by: plan-data.md + -> Blueprint: blueprint-data.md +``` + +Use file ownership tables (from prompts) or directory conventions to map source files to plan/blueprint files. + +### 3.4 Update Context Files + +For each revision target, update: + +1. **Blueprint file:** Add missing requirement with acceptance criteria +2. **Plan file:** Add task referencing the new requirement +3. **Impl tracking:** Record the revision event + +```markdown +# In context/impl/impl-auth.md, add: + +## Revision Log +| Date | Commit | Issue | Blueprint Update | Plan Update | +|------|--------|-------|-------------|-------------| +| 2026-03-14 | abc1234 | 401 not handled | R7 added to blueprint-auth.md | T-AUTH-007 added | +``` + +### 3.5 Run Tests + +After updating context files, run the test suite to verify nothing broke: + +```bash +{BUILD_COMMAND} +{TEST_COMMAND} +``` + +### 3.6 Generate Regression Tests + +For each revision target, generate a regression test that: +- Tests the specific acceptance criteria from the new blueprint requirement +- Would fail if the fix were reverted +- Is included in the standard test suite going forward + +--- + +## 4. Patterns and Anti-Patterns + +### Signs the process is working + +| Pattern | What You Observe | +|---------|--------------------| +| **Declining manual intervention** | Each iteration cycle requires fewer hand-applied fixes because blueprints capture more of the ground truth | +| **Broader blueprint coverage per fix** | A single revision event adds constraints that block an entire family of related defects, not just one | +| **Cross-domain prevention** | Prompt-level adjustments made after a bug in one module prevent analogous bugs from appearing in other modules | +| **Autonomous reproducibility** | After a blueprint update, the iteration loop independently produces the same correction that a human applied manually | + +### Warning signs and remedies + +| Anti-Pattern | Symptom | Remedy | +|-------------|---------|-----| +| **Code-only patches** | The same category of defect resurfaces across iterations | Follow the full 6-step process; never stop after the code fix in Step 1 | +| **Overly specific blueprint additions** | Each revision prevents only the exact bug encountered, while slight variations slip through | Formulate the RULE as a general invariant, not a narrow patch | +| **Skipping verification** | Blueprints are updated but nobody confirms the iteration loop can reproduce the fix independently | Always execute Step 6; a blueprint that does not drive correct generation is incomplete | +| **Brittle over-specification** | Blueprints dictate implementation minutiae, causing breakage on minor refactors | Constrain the WHAT and WHY; leave the HOW to the implementation | +| **Accumulated revision debt** | A backlog of manual fixes sits un-traced, growing with each sprint | Set a cadence (e.g., end of each iteration) to clear the backlog; debt compounds quickly | + +--- + +## 5. When NOT to Revise + +Not every code fix needs revision: + +- **One-off environment issues** (wrong config, missing dependency) -- these are infrastructure, not blueprint gaps +- **Typos and formatting** -- trivial fixes that do not reflect missing requirements +- **Exploratory changes** during prototyping -- blueprints are still being formed +- **Performance optimizations** that do not change behavior -- unless performance is a blueprint requirement + +**Rule of thumb:** If the iteration loop could plausibly reintroduce the bug, revise. If not, skip it. + +--- + +## 6. Revision and Convergence + +Revision directly improves convergence: + +``` +Iteration 1: 350 lines changed, 8 manual fixes needed + -> Revise all 8 fixes into blueprints +Iteration 2: 140 lines changed, 3 manual fixes needed + -> Revise 3 fixes +Iteration 3: 30 lines changed, 1 manual fix needed + -> Revise 1 fix +Iteration 4: 10 lines changed, 0 manual fixes needed + -> Convergence achieved +``` + +Every revision cycle tightens the blueprints, so the iteration loop settles into a stable solution in fewer passes. If convergence is not improving, the most likely cause is that manual fixes are being applied without tracing them back to blueprints. + +**Stalled convergence paired with ongoing manual fixes is a clear sign of revision debt.** The blueprints have not absorbed the lessons from past corrections, so the loop keeps regenerating flawed output that demands human repair. + +--- + +## 7. Integration with Other Blueprint Skills + +- **Convergence monitoring:** Use `bp:convergence-monitoring` to detect when manual fixes are decreasing (good) or increasing (revision debt). +- **Prompt pipeline:** Revision may trigger changes to prompts (Step 6), which affects the `bp:prompt-pipeline` design. +- **Validation-first design:** Stronger validation gates catch issues earlier, reducing the need for revision. +- **Gap analysis:** Systematic gap analysis (`/bp:gap-analysis`) identifies revision targets proactively, rather than waiting for bugs. + +--- + +## Cross-References + +- **Convergence patterns:** See `references/convergence-patterns.md` for how revision drives convergence. +- **Prompt pipeline:** See `bp:prompt-pipeline` skill for how prompt 006 (rewrite pattern) implements automated revision. +- **Impl tracking:** See `bp:impl-tracking` skill for the revision log format in implementation tracking documents. +- **Validation gates:** See `bp:validation-first` skill for validation layers that catch issues before they require revision. diff --git a/plugins/JuliusBrussee/blueprint/skills/speculative-pipeline/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/speculative-pipeline/SKILL.md new file mode 100644 index 0000000..8f1ded2 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/speculative-pipeline/SKILL.md @@ -0,0 +1,268 @@ +--- +name: speculative-pipeline +description: > + A pipeline execution strategy where downstream stages start before upstream stages finish, + using staggered timing with configurable delays. The leader begins first, and followers start + after a delay, building from whatever partial output exists. Combined with convergence loops, + early follower output self-corrects as upstream artifacts solidify. Cuts total pipeline time + dramatically -- a 3-stage pipeline that takes 12 hours sequentially can finish in roughly 7 hours + with speculative-pipeline staggering. + Triggers: "speculative-pipeline", "staggered pipeline", "parallel prompts with delay", + "overlap pipeline stages", "faster pipeline". +--- + +# Speculative-pipeline Strategy + +Run pipeline stages with staggered timing instead of sequentially. The leader starts first; +followers start after a configurable delay and build from whatever upstream output exists at +that point. Combined with convergence loops, followers self-correct as upstream artifacts +arrive and stabilize. + +## Core Principle + +> **Start downstream work early with partial upstream output. Convergence loops correct the +> errors introduced by working from incomplete input.** + +The insight is that waiting for perfect upstream output is wasteful. A follower working from +80% of the upstream artifacts will produce output that is ~60-70% correct on the first pass. +But with convergence loops running, the follower re-reads the upstream artifacts on each +iteration and corrects course. By the time the leader finishes, the follower is already +most of the way done. + +--- + +## The Pattern + +### Sequential (Traditional) + +``` +Stage 1: Specs โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (5 hours) +Stage 2: Plans โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (4 hours) +Stage 3: Implement โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (3 hours) + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + Total: 12 hours +``` + +### Speculative-pipeline (Staggered) + +``` +Stage 1: Specs โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (5 hours) +Stage 2: Plans โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (4 hours, started 1.5h after Stage 1) +Stage 3: Implement โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ (3 hours, started 3h after Stage 1) + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + Total: ~7 hours +``` + +### Why It Works + +1. **Stage 2 starts after a 1.5-hour offset.** By then, Stage 1 has produced a meaningful set of partial specs. +2. **Stage 2 generates plans from whatever specs are available.** Some plans will be built on incomplete information. +3. **Stage 1 keeps refining specs.** When Stage 2 loops back for its next pass, it picks up + the newly completed specs and adjusts its plans accordingly. +4. **Stage 3 starts after a 3-hour offset.** By then, both specs and plans exist in draft form. +5. **All stages self-correct through iteration.** Each pass re-reads the latest upstream artifacts. Mistakes caused + by working from partial input are washed out on subsequent passes. + +The key mechanism is **convergence** -- the iterative loop that re-reads inputs each pass. Without +convergence loops, speculative-pipeline would produce garbage. With them, early errors wash out over +iterations. + +--- + +## Example: 3-Stage Pipeline + +### Directory Structure + +``` +context/ +โ”œโ”€โ”€ specs/ # Stage 1 output: implementation-agnostic specs +โ”œโ”€โ”€ plans/ # Stage 2 output: framework-specific plans +โ”œโ”€โ”€ impl/ # Stage 3 output: implementation tracking +โ””โ”€โ”€ prompts/ + โ”œโ”€โ”€ 001-generate-specs.md # Stage 1 prompt + โ”œโ”€โ”€ 002-generate-plans.md # Stage 2 prompt + โ””โ”€โ”€ 003-implement.md # Stage 3 prompt +``` + +### Terminal Commands + +Open three terminal windows (or use tmux panes): + +```bash +# Terminal 1: Specs from reference materials (leader -- starts immediately) +{LOOP_TOOL} context/prompts/001-generate-specs.md -n 5 -t 2h + +# Terminal 2: Plans from specs (follower -- starts after 1-hour delay) +{LOOP_TOOL} context/prompts/002-generate-plans.md -n 5 -t 2h -d 1h + +# Terminal 3: Implementation from plans (follower -- starts after 2-hour delay) +{LOOP_TOOL} context/prompts/003-implement.md -n 10 -t 1h -d 2h +``` + +**Parameter reference:** +- `-n 5` -- Run up to 5 convergence iterations +- `-t 2h` -- Time budget per iteration (max total time = iterations x budget) +- `-d 1h` -- Delay before starting (speculative-pipeline offset) + +Replace `{LOOP_TOOL}` with your convergence loop runner (any script or tool that repeatedly +executes a prompt against the codebase, committing between iterations). + +### What Happens Chronologically + +| Time | Stage 1 (Specs) | Stage 2 (Plans) | Stage 3 (Implement) | +|------|-----------------|-----------------|---------------------| +| 0:00 | Starts. Reads refs, begins generating specs. | Waiting (1.5h delay). | Waiting (3h delay). | +| 1:30 | Iteration 1 complete. ~50% of specs written. Committed. | Starts. Reads partial specs, begins generating plans. | Waiting. | +| 3:00 | Iteration 2. Specs ~80% complete. | Iteration 1 complete. Plans based on partial specs. Some plans will need correction. | Starts. Reads partial specs + plans, begins implementing. | +| 4:00 | Iteration 3. Specs ~92% complete, converging. | Iteration 2. Re-reads updated specs. Corrects plans. Plans ~65% correct. | Iteration 1 complete. Some implementation based on incomplete plans. | +| 5:00 | Converged. Specs complete. Done. | Iteration 3. Re-reads final specs. Plans ~88% correct. | Iteration 2. Re-reads corrected plans. Fixes implementation. | +| 5:30 | -- | Iteration 4. Plans converged. Done. | Iteration 3. Implementation ~75% correct. | +| 7:00 | -- | -- | Iteration 4-5. Implementation converges. Done. | + +**Result: ~7 hours total versus ~12 hours sequential.** + +--- + +## Choosing Delay Values + +The delay determines how much upstream work exists when the follower starts. Too short and the +follower wastes iterations on garbage input. Too long and you lose the time savings. + +### Guidelines + +| Upstream Stage Duration | Recommended Delay | Rationale | +|------------------------|-------------------|-----------| +| 1-2 hours | 15-30 minutes | Short stages produce useful partial output quickly | +| 2-4 hours | 1 hour | Enough time for the first iteration to complete and commit | +| 4+ hours | 1-2 hours | First iteration should have substantial output | + +### Rules of Thumb + +1. **Delay >= 1 upstream iteration.** The follower should not start until the leader has completed + at least one full iteration and committed results. +2. **Delay < 50% of upstream duration.** If the delay is longer than half the upstream time, the + time savings are marginal. +3. **More follower iterations compensate for shorter delays.** If you start the follower early + (aggressive delay), give it more iterations to converge. + +--- + +## Multi-Stage Pipelines (4+ Stages) + +For pipelines with more than 3 stages, stagger each stage relative to Stage 1: + +```bash +# 5-stage pipeline example +{LOOP_TOOL} {PROMPT_001} -n 5 -t 2h # Stage 1: starts immediately +{LOOP_TOOL} {PROMPT_002} -n 5 -t 2h -d 1h # Stage 2: 1h delay +{LOOP_TOOL} {PROMPT_003} -n 8 -t 1h -d 2h # Stage 3: 2h delay +{LOOP_TOOL} {PROMPT_004} -n 8 -t 1h -d 3h # Stage 4: 3h delay +{LOOP_TOOL} {PROMPT_005} -n 10 -t 45m -d 4h # Stage 5: 4h delay +``` + +**Notice the pattern:** +- Later stages get **more iterations** (they need more correction cycles) +- Later stages get **shorter time budgets per iteration** (less work per stage) +- Delays increase linearly (each stage offset by roughly 1 hour) + +--- + +## When Speculative-pipeline Works Best + +### Good Fit + +- **Long pipelines (3+ stages):** The time savings scale with pipeline depth +- **Stages that share a git repo:** Followers read upstream commits automatically +- **Stages with convergence loops:** The self-correction mechanism is essential +- **Specs that are mostly stable after 1-2 iterations:** Partial specs are useful early + +### Poor Fit + +- **Stages with hard dependencies:** If Stage 2 literally cannot start without Stage 1's + complete output (e.g., code generation that requires a fully resolved type system), the + follower will produce only errors +- **Single-iteration stages:** Without convergence loops, there is no self-correction +- **Very short pipelines (2 stages, <1 hour each):** The overhead of staggering is not + worth the small time savings + +--- + +## Monitoring Speculative-pipeline Execution + +### What to Watch + +1. **Follower diff sizes per iteration.** If the follower's diffs are large on every iteration + (not decreasing), it is thrashing -- the delay was too short or the upstream output is + too unstable. +2. **Follower convergence rate.** The follower should converge within 1-2 iterations of the + leader finishing. If it takes many more, the stages may have a hard dependency. +3. **Git commit frequency.** Both leader and follower should be committing regularly. If commits + stall, the agent may be stuck. + +### Convergence Signals + +A speculative-pipeline pipeline has converged when: +- All stages have completed their iteration loops +- The final iteration of each stage produces minimal diffs +- Build and test gates pass on the merged output + +### Thrashing Detection + +**Thrashing** = the follower keeps making large changes because upstream output keeps changing. + +Signs of thrashing: +- Follower diff sizes do not decrease across iterations +- Follower reverts changes it made in previous iterations +- Build failures increase instead of decreasing + +**Fix thrashing by:** +1. Increasing the delay (give the leader more time to stabilize) +2. Reducing follower iterations (let upstream settle first) +3. Adding a "wait for upstream convergence" gate between stages + +--- + +## Combining with Agent Teams + +In multi-agent setups, speculative-pipeline applies at the pipeline level, not the agent team level: + +``` +Pipeline Level (speculative-pipeline timing): + Stage 1 (Specs) โ†’ Single agent or agent team + Stage 2 (Plans) โ†’ Single agent or agent team (starts after delay) + Stage 3 (Implement) โ†’ Agent team dispatched with `isolation: "worktree"` via Agent tool (starts after delay) +``` + +Each stage can internally use agent teams (multiple teammates working in parallel on different +domains), but the *stages themselves* are staggered using speculative-pipeline timing. + +**Do not confuse:** +- **Leader-follower:** Pipeline stages overlapping in time +- **Agent teams:** Multiple agents working in parallel within a single stage + +They are orthogonal and composable. + +--- + +## Implementation Checklist + +When setting up a speculative-pipeline pipeline: + +- [ ] Define the pipeline stages (typically: specs, plans, implement) +- [ ] Create a prompt file for each stage with explicit input/output directories +- [ ] Ensure each stage reads from upstream directories and writes to its own directory +- [ ] Configure convergence loop for each stage with appropriate iteration counts +- [ ] Choose delays: first follower at ~1 upstream iteration, subsequent at ~1h increments +- [ ] Set up terminal sessions (one per stage) or use tmux +- [ ] Monitor: watch for convergence (decreasing diffs) vs thrashing (constant large diffs) +- [ ] After all stages complete, run full build + test validation on the merged output + +--- + +## Cross-References + +- **prompt-pipeline** -- How to design the prompt files that each stage executes +- **convergence-monitoring** -- How to detect convergence vs ceiling in each stage +- **methodology** -- Where speculative-pipeline fits in the DABI lifecycle +- **validation-first** -- Validation gates that run after each stage completes +- **context-architecture** -- Directory structure that stages read from and write to diff --git a/plugins/JuliusBrussee/blueprint/skills/ui-craft/SKILL.md b/plugins/JuliusBrussee/blueprint/skills/ui-craft/SKILL.md new file mode 100644 index 0000000..c6b36f1 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/ui-craft/SKILL.md @@ -0,0 +1,582 @@ +--- +name: ui-craft +description: | + Authoritative guide for implementing stunning, accessible, performant UI. Synthesizes + design engineering philosophy, accessibility standards, animation principles, spatial design, + typography, color systems, and component craft into a single actionable reference. + Complements the design-system skill (which covers DESIGN.md spec writing) by covering + the HOW of implementation. + Trigger phrases: "build UI", "create component", "landing page", "make it look good", + "frontend", "design", "polish UI", "implement design", "make it beautiful", + "UI implementation", "component styling", "animation", "accessibility" +--- + +# UI Craft: Implementation Guide for Exceptional Interfaces + +> If a DESIGN.md exists at the project root, its tokens and specifications override all defaults in this skill. This skill provides sensible defaults for when no design system exists, and implementation guidance that applies regardless. + +> For deep dives on any section, see the reference files in this skill's `references/` directory. + +--- + +## 1. Core Philosophy + +Taste is trained, not innate. Study why great interfaces feel right. Deconstruct apps you admire โ€” the spacing, the timing, the weight of a shadow. The gap between "fine" and "exceptional" is built from hundreds of micro-decisions that users feel but never consciously notice. + +**Unseen details compound.** A single rounded corner, a single eased transition, a single well-chosen shadow โ€” none of these matter alone. Together they become "a thousand barely audible voices singing in tune." The cumulative effect is what separates craft from output. + +**Beauty is leverage.** Polish is not vanity. Good defaults, considered typography, and intentional motion are real differentiators. Users trust interfaces that feel cared for. Investors notice. Competitors can't easily replicate taste. + +**Intentionality over intensity.** Both bold maximalism and refined minimalism work โ€” what fails is the absence of a clear point of view. Every visual decision should trace back to a deliberate conceptual direction. If you can't articulate WHY a choice was made, reconsider it. + +**Choose a direction and execute with precision.** Don't hedge between styles. A brutalist page committed fully will always outperform a page that's "a little bit of everything." Commit, then refine. + +**NEVER produce generic "AI slop" aesthetics.** No gratuitous gradients on white backgrounds. No cookie-cutter hero sections with stock illustrations. No safe, forgettable layouts that could belong to any product. Every interface should have a point of view that makes it recognizable. + +--- + +## 2. The Priority Stack + +When implementing UI, work through these priorities in order. Higher priorities are non-negotiable; lower priorities are polish that compounds quality. + +| Priority | Level | What It Means | +|----------|-------|---------------| +| **Accessibility** | CRITICAL | Contrast 4.5:1, keyboard nav, ARIA semantics, visible focus rings. Ship nothing that excludes users. | +| **Performance** | HIGH | WebP/AVIF images, lazy loading below fold, CLS < 0.1, transform-only animations on the compositor thread. | +| **Typography** | HIGH | Font smoothing, text-wrap balance/pretty, tabular-nums for data, 65ch max line length. | +| **Layout & Spatial** | HIGH | 4/8px grid, concentric border radius, optical alignment over geometric. | +| **Color & Theme** | MEDIUM | HSL custom properties, semantic tokens, dark mode pairs tested separately. | +| **Motion & Interaction** | MEDIUM | Frequency-based animation decisions, 150-300ms durations, ease-out default. | +| **Polish & Details** | LOW | Layered shadows over borders, press feedback on buttons, staggered enter animations. | + +Never skip a CRITICAL/HIGH item to chase a LOW item. A beautifully animated button that fails keyboard navigation is a net negative. + +--- + +## 3. Aesthetic Direction + +Before writing a single line of CSS, commit to a bold aesthetic direction. The most common failure mode in AI-generated UI is convergence on the same safe, forgettable look. + +### Pick a Tone + +Choose one and commit fully: + +- **Brutally minimal** โ€” generous whitespace, monospace type, stark contrast, near-zero decoration +- **Maximalist chaos** โ€” layered textures, clashing type scales, dense information, intentional visual noise +- **Retro-futuristic** โ€” CRT glow effects, monospace terminals, scan lines, neon on dark +- **Organic / natural** โ€” earth tones, rounded shapes, paper textures, hand-drawn accents +- **Luxury / refined** โ€” serif headlines, muted palettes, ample negative space, subtle gold or cream accents +- **Editorial / magazine** โ€” dramatic type hierarchy, full-bleed imagery, grid-breaking layouts +- **Playful / bold** โ€” bright primaries, chunky borders, exaggerated shadows, bouncy motion + +### Match Complexity to Vision + +Maximalist design demands elaborate code โ€” layered backgrounds, complex grid structures, multiple font stacks. Minimalist design demands surgical precision โ€” every pixel of spacing matters more when there's nothing to hide behind. + +### The Ban List (When No DESIGN.md Exists) + +When building without an existing design system, avoid these overused defaults that signal "AI-generated": + +- **Fonts**: Inter, Roboto, Arial, system-ui as display fonts, Space Grotesk +- **Colors**: Purple-to-blue gradients on white backgrounds +- **Patterns**: Generic hero with centered text + CTA + stock illustration + +Vary between light and dark themes, different font pairings, different aesthetic directions. Never converge on the same choices across projects. + +### Visual Texture + +Add depth through: gradient meshes, noise/grain overlays (`filter: url(#noise)`), layered transparencies, subtle background patterns, duotone image treatments. + +**DESIGN.md overrides this entire section.** If DESIGN.md specifies Inter, use Inter. If it specifies purple gradients, use them. The ban list only applies when no design system exists and you're making aesthetic choices from scratch. + +--- + +## 4. Typography Essentials + +Typography is the single highest-leverage design element. Get it right and mediocre layouts still feel good. Get it wrong and nothing else saves it. + +### Root Setup + +```css +html { + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + text-rendering: optimizeLegibility; +} +``` + +Apply font smoothing to the root layout. On macOS, the default sub-pixel rendering makes text appear heavier than the designer intended. + +### Text Wrapping + +```css +h1, h2, h3, h4, h5, h6 { + text-wrap: balance; +} + +p, li, dd, blockquote { + text-wrap: pretty; +} +``` + +`balance` distributes heading lines evenly. `pretty` avoids orphaned words in body text. + +### Numeric Display + +```css +.data-value, .price, .counter, [data-numeric] { + font-variant-numeric: tabular-nums; +} +``` + +Use `tabular-nums` for any number that updates dynamically โ€” prices, counters, table columns. Without it, layout shifts as digit widths change. + +### Scale and Rhythm + +- **Base size**: 16px minimum for body text. Never go below 14px for any readable content. +- **Line height**: 1.5-1.75 for body text, 1.1-1.3 for large headings. +- **Max line length**: `max-width: 65ch` for body text. Long lines destroy readability. +- **Type scale**: Pick a consistent scale and stick to it: 12 / 14 / 16 / 18 / 24 / 32 / 48 / 64. + +### Font Pairing + +Pair a distinctive display font with a refined body font. The display font carries personality; the body font carries readability. Use `font-weight` for hierarchy within a family: + +- **Headings**: 600-700 (semibold to bold) +- **Body**: 400 (regular) +- **Labels / UI**: 500 (medium) + +Always include font stack fallbacks: + +```css +--font-display: "Instrument Serif", "Georgia", serif; +--font-body: "Sรถhne", "Helvetica Neue", sans-serif; +--font-mono: "JetBrains Mono", "Fira Code", monospace; +``` + +--- + +## 5. Color & Theme + +### HSL Custom Properties (shadcn Pattern) + +```css +:root { + --background: 0 0% 100%; + --foreground: 222.2 84% 4.9%; + --primary: 222.2 47.4% 11.2%; + --primary-foreground: 210 40% 98%; + --secondary: 210 40% 96.1%; + --secondary-foreground: 222.2 47.4% 11.2%; + --muted: 210 40% 96.1%; + --muted-foreground: 215.4 16.3% 46.9%; + --accent: 210 40% 96.1%; + --accent-foreground: 222.2 47.4% 11.2%; + --destructive: 0 84.2% 60.2%; + --destructive-foreground: 210 40% 98%; + --border: 214.3 31.8% 91.4%; + --ring: 222.2 84% 4.9%; + --radius: 0.5rem; +} +``` + +Define semantic tokens: primary, secondary, destructive, muted, accent, background, foreground. Reference colors by semantic name โ€” never hardcode hex values in components. + +### Dark Mode + +```css +.dark { + --background: 222.2 84% 4.9%; + --foreground: 210 40% 98%; + /* ... desaturated, lighter tonal variants โ€” NOT simply inverted */ +} +``` + +Dark mode is not "invert colors." Use desaturated, lighter tonal variants. Backgrounds go dark but not pure black (`#000`). Text goes light but not pure white (`#fff`). Test contrast separately for dark mode โ€” what passes in light may fail in dark. + +### Contrast Requirements + +- **WCAG AA minimum**: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+ regular) +- Never convey information by color alone โ€” always pair with an icon, label, or pattern +- Test with browser devtools contrast checker or axe-core + +### Color Confidence + +Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Pick one or two hero colors and let the rest of the palette recede. A confident palette has clear hierarchy; an uncertain palette spreads color evenly and feels flat. + +--- + +## 6. Spatial Design + +### Concentric Border Radius + +This is the single most common thing that makes nested UI elements feel "off": + +``` +outer_radius = inner_radius + padding +``` + +```css +/* Correct: concentric */ +.card { border-radius: 16px; padding: 8px; } +.card-inner { border-radius: 8px; } /* 16 - 8 = 8 */ + +/* Wrong: same radius on parent and child */ +.card { border-radius: 12px; } +.card-inner { border-radius: 12px; } /* Looks bloated */ +``` + +When geometric centering looks off, align optically. Play/pause icons, dropdown carets, and asymmetric glyphs often need 1-2px manual nudges to look centered. + +### Shadows Over Borders + +Layer multiple transparent `box-shadow` values for natural depth instead of using borders: + +```css +.elevated { + box-shadow: + 0 1px 2px rgba(0, 0, 0, 0.04), + 0 2px 4px rgba(0, 0, 0, 0.04), + 0 4px 8px rgba(0, 0, 0, 0.04); +} +``` + +Multiple shadows at different spreads mimic how light works. A single hard shadow looks artificial. + +### Image Outlines + +Add a subtle inset outline to images and media for consistent depth against varied backgrounds: + +```css +img, video { + outline: 1px solid rgba(0, 0, 0, 0.06); + outline-offset: -1px; +} +``` + +### Spacing Scale + +Use a 4px / 8px base incremental system. Every spacing value should be a multiple of 4: + +`4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128` + +### Hit Areas + +Minimum 44x44px for all interactive elements. If the visual element is smaller, extend the hit area with a pseudo-element: + +```css +.small-button::before { + content: ""; + position: absolute; + inset: -8px; +} +``` + +### Z-Index Scale + +Define a layered scale and never use arbitrary values: + +```css +--z-base: 0; +--z-dropdown: 10; +--z-sticky: 20; +--z-overlay: 40; +--z-modal: 100; +--z-toast: 1000; +``` + +--- + +## 7. Motion & Interaction + +### The Frequency-Based Decision Framework + +This is the most important mental model for animation decisions: + +| Frequency | Examples | Animation | +|-----------|----------|-----------| +| **100+ times/day** | Keyboard shortcuts, command palette actions, tab switches | **None.** Zero animation. Instant. | +| **Tens of times/day** | Hover effects, list item navigation, toggles | **Remove or drastically reduce.** 50-100ms max. | +| **Occasional** | Modals, drawers, toasts, page transitions | **Standard animation.** 150-300ms. | +| **Rare / first-time** | Onboarding, celebrations, empty states | **Can add delight.** 300-500ms, more elaborate. | + +High-frequency animations feel sluggish. Low-frequency animations without motion feel jarring. Match the animation budget to usage frequency. + +### Custom Easing Curves + +Built-in CSS easings (`ease`, `ease-in-out`) are too weak. Define custom curves: + +```css +:root { + --ease-out: cubic-bezier(0.23, 1, 0.32, 1); + --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1); + --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1); + --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1); +} +``` + +### Duration Guide + +| Element | Duration | +|---------|----------| +| Buttons, toggles | 100-160ms | +| Tooltips | 125-200ms | +| Dropdowns, popovers | 150-250ms | +| Modals, drawers | 200-500ms | +| Page transitions | 250-400ms | + +UI animations should stay under 300ms. Never use `ease-in` for UI animations โ€” it front-loads the pause and feels sluggish. + +### Enter/Exit Asymmetry + +Exits should be softer and faster than enters. An enter animation at 250ms should have its exit at 150-200ms. + +### Split and Stagger Enter Animations + +When multiple elements enter the viewport, stagger them by semantic chunks with ~50-100ms delay: + +```css +.stagger-item { + animation: fadeSlideIn 300ms var(--ease-out) both; +} +.stagger-item:nth-child(1) { animation-delay: 0ms; } +.stagger-item:nth-child(2) { animation-delay: 60ms; } +.stagger-item:nth-child(3) { animation-delay: 120ms; } +``` + +### Scale Animations + +Never animate from `scale(0)`. Start from `scale(0.9)` or higher, combined with opacity: + +```css +@keyframes scaleIn { + from { opacity: 0; transform: scale(0.95); } + to { opacity: 1; transform: scale(1); } +} +``` + +### Press Feedback + +Every pressable element should scale down slightly on `:active`: + +```css +button:active { + transform: scale(0.97); +} +``` + +### Interruptibility + +Use CSS transitions (not keyframe animations) for interactive state changes. Transitions can be interrupted mid-way; keyframes cannot. This matters for hover states, toggles, and any element the user might interact with rapidly. + +### Popover Origin + +Make popovers transform-origin aware โ€” they should grow from their trigger element, not from center. Exception: modals always originate from center. + +### Tooltip Hover Delay + +Skip the tooltip delay on subsequent hovers. If the user has already waited for one tooltip, show the next one immediately. + +### Reduced Motion + +```css +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.01ms !important; + transition-duration: 0.01ms !important; + } +} +``` + +Respect `prefers-reduced-motion`. Reduce animations โ€” don't eliminate opacity and color transitions entirely, as those provide important feedback. + +### Hover Gate + +Gate hover animations behind a media query so touch devices don't trigger stuck hover states: + +```css +@media (hover: hover) and (pointer: fine) { + .card:hover { transform: translateY(-2px); } +} +``` + +> Reference `references/animation-playbook.md` for deep dives on spring physics, gesture-driven animation, and complex choreography. + +--- + +## 8. Component Craft + +### Primitives + +Use Radix UI primitives for accessible, unstyled foundations. Use CVA (class-variance-authority) for type-safe component variants: + +```tsx +import { cva } from "class-variance-authority"; + +const buttonVariants = cva( + "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2", + { + variants: { + variant: { + default: "bg-primary text-primary-foreground hover:bg-primary/90", + destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90", + outline: "border border-input hover:bg-accent hover:text-accent-foreground", + ghost: "hover:bg-accent hover:text-accent-foreground", + }, + size: { + sm: "h-9 px-3 text-sm", + default: "h-10 px-4 py-2", + lg: "h-11 px-8 text-lg", + }, + }, + defaultVariants: { variant: "default", size: "default" }, + } +); +``` + +### Button + +- Scale on press (`transform: scale(0.97)` on `:active`) +- Visible focus ring (never `outline: none` without replacement) +- Loading state with spinner replacing label, maintaining button dimensions +- Disabled state at `opacity: 0.5` with `pointer-events: none` + +### Card + +- Concentric border radius between card and inner elements +- Layered shadows (not borders) for depth +- Hover state: subtle elevation change (`translateY(-1px)` + shadow increase) + +### Dialog / Modal + +- Focus trap (keyboard cannot escape to elements behind) +- ESC to close, click outside overlay to close +- `transform-origin: center`, fade + scale enter animation +- `aria-modal="true"`, `role="dialog"`, `aria-labelledby` + +### Form + +- Visible labels always โ€” never placeholder-only inputs +- Error messages near the field with `aria-live="polite"` for screen readers +- Progressive disclosure: show advanced fields only when needed +- Use React Hook Form + Zod for validation + +### Theming + +Use shadcn CSS variable pattern (HSL format) for all component colors. Wrap client-interactive components in server components for Next.js App Router compatibility. + +> Reference `references/component-patterns.md` for the full component catalog with copy-paste implementations. + +--- + +## 9. Accessibility Essentials + +### Semantic HTML First + +Use `` +- `aria-labelledby` to associate headings with sections +- `aria-describedby` to link help text or error messages to inputs +- `aria-live="polite"` for dynamic content updates (toast messages, form errors) +- `aria-hidden="true"` for decorative elements (icons next to text labels) +- `aria-expanded` for toggleable elements (dropdowns, accordions) + +### Color and Contrast + +- WCAG AA: 4.5:1 for normal text, 3:1 for large text +- Never use color as the sole indicator โ€” pair with icons, text, or patterns +- Test in both light and dark modes + +### Images and Media + +- Descriptive `alt` text for meaningful images: `alt="Dashboard showing 23% revenue growth"` +- Empty `alt=""` for purely decorative images +- Captions for video, transcripts for audio + +### Navigation Aids + +- **Skip link**: first focusable element, hidden until focused: + +```html + + Skip to main content + +``` + +- **Heading hierarchy**: sequential h1 through h6, no level skips. One `

` per page. + +### Touch Targets + +- Minimum 44x44px interactive area +- 8px minimum spacing between adjacent touch targets +- Extend small visual elements with invisible padding or pseudo-elements + +### Testing + +- **Automated**: axe-core in CI, Lighthouse accessibility score 90+ +- **Manual**: full keyboard-only navigation test +- **Screen reader**: test with VoiceOver (macOS) or NVDA (Windows) +- **Visual**: zoom to 200%, check nothing breaks or overlaps + +> Reference `references/accessibility-checklist.md` for the full audit guide with pass/fail criteria. + +--- + +## 10. Pre-Delivery Review + +Run through this checklist before considering any UI implementation complete: + +### Typography +- [ ] Font smoothing applied (`-webkit-font-smoothing: antialiased`) +- [ ] Headings use `text-wrap: balance` +- [ ] Dynamic numbers use `font-variant-numeric: tabular-nums` + +### Color +- [ ] All colors referenced via semantic tokens, no hardcoded hex in components +- [ ] Color contrast meets WCAG AA (4.5:1 normal text, 3:1 large text) +- [ ] Dark mode tested separately for contrast + +### Spatial +- [ ] Nested rounded elements use concentric border radius +- [ ] Spacing follows 4px / 8px scale consistently +- [ ] Interactive elements have 44x44px minimum hit area +- [ ] Shadows used instead of borders where appropriate + +### Motion +- [ ] Animation frequency matches usage frequency (no animation on high-frequency actions) +- [ ] No `transition: all` anywhere โ€” specific properties only +- [ ] Enter animations split and staggered where multiple elements appear +- [ ] `prefers-reduced-motion` respected + +### Accessibility +- [ ] All interactive elements keyboard accessible +- [ ] Focus rings visible on keyboard navigation (never `outline: none` without replacement) +- [ ] Semantic HTML used before ARIA +- [ ] `aria-live` on dynamic content updates + +> Reference `references/review-checklist.md` for the extended 30-item checklist with severity ratings and automated testing commands. diff --git a/plugins/JuliusBrussee/blueprint/skills/ui-craft/references/accessibility-checklist.md b/plugins/JuliusBrussee/blueprint/skills/ui-craft/references/accessibility-checklist.md new file mode 100644 index 0000000..d576ac5 --- /dev/null +++ b/plugins/JuliusBrussee/blueprint/skills/ui-craft/references/accessibility-checklist.md @@ -0,0 +1,425 @@ +# WCAG 2.1 AA Accessibility Audit Guide + +Comprehensive checklist for building accessible web interfaces. Every requirement maps to WCAG 2.1 Level AA success criteria. + +--- + +## 1. Semantic HTML Priority + +ALWAYS use semantic HTML before reaching for ARIA. Native elements carry built-in keyboard behavior, focus management, and screen reader announcements that ARIA can only approximate. + +### Element Selection Rules + +| Instead of | Use | +|---|---| +| `
` | `