From 39356ebdbf6e1f6b3a948f8d3a6eb9c92537a574 Mon Sep 17 00:00:00 2001 From: jared Date: Wed, 15 Jul 2026 15:41:09 -0400 Subject: [PATCH] wip: checkpoint before hygiene cleanup --- .dochygiene-rules.json | 71 +- ...ugin-not-a-separate-cc-sdlc-marketplace.md | 27 + ...dan-agentic-engineering-overview-video.txt | 680 ++++++++++++++++++ plugins/os-sdlc/.claude-plugin/plugin.json | 5 + plugins/os-sdlc/OVERVIEW.md | 127 ++++ 5 files changed, 879 insertions(+), 31 deletions(-) create mode 100644 docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md create mode 100644 indydevdan-agentic-engineering-overview-video.txt create mode 100644 plugins/os-sdlc/.claude-plugin/plugin.json create mode 100644 plugins/os-sdlc/OVERVIEW.md diff --git a/.dochygiene-rules.json b/.dochygiene-rules.json index f7314f1..2755019 100644 --- a/.dochygiene-rules.json +++ b/.dochygiene-rules.json @@ -1,6 +1,24 @@ { "schema_version": 1, "rules": [ + { + "glob": "docs/orchestration-audit/auditor-reports/S*-report.md", + "lifetime": "delete-once-served", + "served_when": "The run's synthesis findings doc (docs/orchestration-audit/-findings.md) has been written and verified; these per-session reports are the raw inputs it condenses.", + "confirmed_by": "human", + "confirmed_on": "2026-07-15", + "source": "calibration pass #2 (2026-07-15)", + "note": "Per-session raw auditor reports condensed by the run's synthesis findings doc; delete-once-served is always confirm-tier (ADR-0039)." + }, + { + "glob": "plugins/*/HANDOFF-*.md", + "lifetime": "delete-once-served", + "served_when": "The handoff it describes has been picked up and its follow-on work completed in a later session.", + "confirmed_by": "human", + "confirmed_on": "2026-07-15", + "source": "calibration pass #1 (lifecycle-aware-doc-hygiene)", + "note": "Classifier-judged served_when \u2014 always confirm-tier by ADR-0039; never auto-deleted." + }, { "glob": "autoresearch/classic-*/", "lifetime": "temporary", @@ -31,32 +49,6 @@ "source": "calibration pass #1 (lifecycle-aware-doc-hygiene)", "note": "Regenerable precompute for the orchestration IRL audit; the audit skill rebuilds them on each run." }, - { - "glob": "plugins/*/.pytest_cache/", - "lifetime": "temporary", - "retain_recent": 0, - "max_age_days": 7, - "confirmed_by": "human", - "confirmed_on": "2026-07-15", - "source": "calibration pass #1 (lifecycle-aware-doc-hygiene)", - "note": "Regenerable pytest cache. Judge noted a .gitignore entry may be preferable long-term." - }, - { - "glob": "openspec/specs/**", - "lifetime": "keep", - "confirmed_by": "human", - "confirmed_on": "2026-07-15", - "source": "conversation 2026-07-15 (openspec lifecycle rules)", - "note": "Live OpenSpec capability specs — source of truth future changes diff against; never age out." - }, - { - "glob": "plugins/*/openspec/specs/**", - "lifetime": "keep", - "confirmed_by": "human", - "confirmed_on": "2026-07-15", - "source": "conversation 2026-07-15 (openspec lifecycle rules)", - "note": "Live OpenSpec capability specs — source of truth future changes diff against; never age out." - }, { "glob": "openspec/changes/archive/*/", "lifetime": "temporary", @@ -67,6 +59,16 @@ "source": "conversation 2026-07-15 (openspec lifecycle rules)", "note": "Archived change dirs are redundant once synced into specs/ and stay recoverable from git history; age out after a quarter." }, + { + "glob": "plugins/*/.pytest_cache/", + "lifetime": "temporary", + "retain_recent": 0, + "max_age_days": 7, + "confirmed_by": "human", + "confirmed_on": "2026-07-15", + "source": "calibration pass #1 (lifecycle-aware-doc-hygiene)", + "note": "Regenerable pytest cache. Judge noted a .gitignore entry may be preferable long-term." + }, { "glob": "plugins/*/openspec/changes/archive/*/", "lifetime": "temporary", @@ -78,13 +80,20 @@ "note": "Archived change dirs are redundant once synced into specs/ and stay recoverable from git history; age out after a quarter." }, { - "glob": "plugins/*/HANDOFF-*.md", - "lifetime": "delete-once-served", - "served_when": "The handoff it describes has been picked up and its follow-on work completed in a later session.", + "glob": "openspec/specs/**", + "lifetime": "keep", "confirmed_by": "human", "confirmed_on": "2026-07-15", - "source": "calibration pass #1 (lifecycle-aware-doc-hygiene)", - "note": "Classifier-judged served_when — always confirm-tier by ADR-0039; never auto-deleted." + "source": "conversation 2026-07-15 (openspec lifecycle rules)", + "note": "Live OpenSpec capability specs \u2014 source of truth future changes diff against; never age out." + }, + { + "glob": "plugins/*/openspec/specs/**", + "lifetime": "keep", + "confirmed_by": "human", + "confirmed_on": "2026-07-15", + "source": "conversation 2026-07-15 (openspec lifecycle rules)", + "note": "Live OpenSpec capability specs \u2014 source of truth future changes diff against; never age out." } ] } diff --git a/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md b/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md new file mode 100644 index 0000000..2c6e681 --- /dev/null +++ b/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md @@ -0,0 +1,27 @@ +--- +id: "0037" +date: 2026-07-14 +status: Accepted +supersedes: +superseded-by: +affected-paths: [plugins/os-sdlc/, docs/matt-pocock-skills-v1.1-notes.md] +affected-components: [os-sdlc, os-backlog, os-adr, os-vault] +--- + +# 0037 — os-sdlc lives inside cc-os as a new plugin, not a separate cc-sdlc marketplace + +## Context + +User is adopting Matt Pocock's v1.1 skill lifecycle (grill/to-spec/to-tickets/implement/wayfinder/research/code-review) and wants to blend it with ~/dev/delta-refinery's heavier multi-level pipeline pattern plus cc-os's existing os-backlog/os-adr systems, to automate large chunks of the dev process for upcoming projects. The open question was whether this SDLC layer should be a new plugin inside the cc-os monorepo (registered in the existing local-plugins marketplace) or a separate cc-sdlc marketplace/repo, motivated by wanting shared tooling reusable across harnesses (Claude Code/Codex/pi) and separation of concerns from general os-* tooling. + +## Decision + +os-sdlc lives at plugins/os-sdlc/ inside the cc-os repo, registered in the existing local-plugins marketplace, following the os-[domain] naming convention (cc-os-plugin-skill-naming-convention.md). It is scoped to include skills, agents, hooks, reference material, and scripts (not skills-only like most current os-* plugins). The first skill is /os-sdlc:review, cherry-picking Matt Pocock's standards-conformance + spec-fidelity + Fowler refactor-smell review axes, coexisting with the existing generic /code-review (correctness + reuse/simplification) rather than replacing it. Full pipeline design (how much of Delta Refinery's multi-level/resumable-handoff machinery to adopt, how implement/wayfinder are shaped) is deferred to a follow-up brainstorming session; plugins/os-sdlc/OVERVIEW.md is the launching-point doc for that session. + +## Consequences + +Adding a new SDLC lifecycle domain becomes easier: it reuses the existing marketplace manifest, refresh-plugins tooling, and os-[domain] naming convention instead of standing up new infrastructure. os-sdlc's skills can call directly into os-backlog (tickets) and os-adr (decisions) as sibling plugins in the same repo, keeping ADR-0023's cooperating-plugins bet intact. The tradeoff: os-sdlc is not independently reusable outside cc-os without extraction later if the user ever wants to publish/share just the SDLC layer decoupled from the personal vault/memory stack — that would require a future split, not ruled out here, just not chosen now. Running two coexisting review commands (/code-review and /os-sdlc:review) is an explicit, intentional consequence of this decision, not an oversight. + +## Alternatives rejected + +Separate cc-sdlc marketplace/repo — rejected because the user confirmed it would be installed globally too, so a split buys no functional/loading separation, only a second repo/manifest to keep in sync, and it fragments coupling to os-backlog/os-adr/os-vault across repos against ADR-0023's cooperating-plugins bet. Enhancing the existing generic /code-review in place instead of a namespaced /os-sdlc:review — rejected because the two review skills serve genuinely different axes (correctness/reuse/simplification vs standards-doc conformance/spec-fidelity/refactor-smells) and the user explicitly chose coexistence over a merge. diff --git a/indydevdan-agentic-engineering-overview-video.txt b/indydevdan-agentic-engineering-overview-video.txt new file mode 100644 index 0000000..34e2e56 --- /dev/null +++ b/indydevdan-agentic-engineering-overview-video.txt @@ -0,0 +1,680 @@ +source: https://youtu.be/VQy50fuxI34?si=fENPEi7_hFppIftM +Forget Loop Engineering +0:00 +It's time for us to talk about loop engineering. I was hoping this would just blow over after a couple weeks. I +0:05 +was hoping a cracked engineer would call this stupid phrase what it really is, but no one has. So, I'll do it myself. +0:13 +Forget about loop engineering. It's the wrong way to think about building valuable software with agents at scale +0:20 +consistently. Loop engineering is a terrible rebrand of the software development life cycle. It's as unclear +0:28 +as it is hype-filled. In this video, we simplify loop engineering and call it +0:33 +what it really is. If you understand this concept properly, we're going to break down in this video, [music] +0:39 +you'll accelerate far ahead of the AI industry. Clarity and simplicity of +0:45 +information gives you [music] speed and performance in your work. It's much more +0:50 +valuable and helpful to think about building with [music] agents as if you're building developer workflows +0:57 +inside your software factory. Your props [music] go into your software factory. A +1:03 +specific workflow runs. Each workflow [music] is a combination of code plus agents and then your results [music] +1:10 +come out. Forget about loop engineering. Focus your valuable engineering time and +1:16 +tokens on building AI developer workflows. +Who Is IndyDevDan? +1:25 +So, first off, who am I to go up against big ideas from AI engineers like Boris +1:31 +Churnney from Anthropic and Peter Steinberg, now from OpenAI? If you already know who I am and the work I've +1:37 +done, or you don't care, skip to this timestamp. My name is Dan Eisler aka Indie Dev Dan. I'm a software engineer +1:43 +with over 15 years of EXP. I started out building Adobe Flash games with Action Script 2 and three with my brothers. I +1:50 +interned at Blizzard and then I quickly moved into the finance and accounting space programming in C, TypeScript, +1:57 +Python, God awful React and God bless Evanu for creating Vue. I was AI coding +2:03 +before anyone had a name for it with tools like Ader and classic models like GPT3.5 Turbo, GPT4, and Sonnet 3. Tools +2:12 +and models you've probably never heard of or used. I own the domain name agenticengineer.com +2:18 +where thousands of engineers you've heard of from companies you know have improved their agentic engineering +2:24 +thanks to information products I've built by hand. But anyone can pick up a domain name and create a course though, +2:31 +right? Sure. I also have an irrefutable trail of code and content for engineers +2:37 +on GitHub and this YouTube channel every single week for years now. You can see +2:42 +myself and engineers that follow this channel consistently ahead of the curve of the AI industry. I don't just farm +2:49 +news for views like every other tech content creator. On this channel, we think, plan, and build. Every few +2:56 +months, it's important for me to sit down and say this. I'm not a content creator. I'm a software engineer that +3:03 +does content creation on the side. Why? Because this technology is too valuable +3:09 +to fall into the hands of a lucky few. And yes, I sell courses. And yes, I +3:14 +benefit from it. Big whoop. Don't do anything you're great at for free. Welcome to capitalism. Enough about me. +3:19 +I don't show up here every single Monday to gloat and talk about myself. I show up here to give engineers like you an +3:25 +advantage you can use to accelerate your career, your work, your business, your engineering in the age of AI, no hype. +3:33 +So, forget about loop engineering and focus on this instead. There are now +Your 3 Actors of Value Creation +3:39 +three actors of value creation for engineering work. The engineers like you and I, there are the agents and there's +3:46 +the code. Knowing when and where to place each of these is the name of the +3:52 +game of agentic engineering. And you might be thinking, where is he going with this? How does this relate to loop engineering and developer workflows? +3:59 +Stick with me here. We're going to work up to it. If you master the fundamentals, you'll master the compositions. Everyone in their AI +4:05 +psychosis seems to forget code is fast, always runs the same way unless you tell +4:11 +it not to. And guess what? It costs nothing. There are no token costs associated with code. the thing that +4:17 +truly moves at light speed. There's a hidden cost to implementing every single one of these actors of value creation. +4:25 +Everyone's talking about agents. We're all well aware of the cost of engineers, but code is the unsung hero of all of +4:32 +this. Consistent value creation creates consistent business value. And out of these three, code is the most reliable +4:39 +by miles followed by engineers [music] and then agents. So let's start with the +Your First Ever AI Developer Workflow +4:44 +most basic developer workflow. +4:50 +An engineer prompts an LLM and the engineer reviews the result. This is the simple foundation that makes up every +4:58 +single loop, every single workflow, every single piece of work moving forward. Now, of course, we're not just +5:05 +using the LLM anymore. In this central node, we have an agent. Insert your favorite agent. Insert your favorite +5:11 +model. It doesn't matter anymore. It's about the workflow that you and I execute every single day. Great. Let's +5:19 +scale it up. Now, we have code, agents, and engineers all involved in the +5:24 +process. We're building up to more and more advanced developer workflows. You'll notice something really important +5:31 +here. We now have code. In this case, we're just running a llinter. We have a condition. If the llinter fails, the +5:37 +results go back into our build agent. If they're successful, it passes. This condition and this routing back to our +5:45 +build agent creates our first loop. Hence the term loop engineering. But +5:50 +loop engineering is too simple. It's too inaccurate. And there's a lot more to this story. So what comes next? How can +5:56 +we continue to enhance our developer workflow to get better results? We can of course add more deterministic code. +Adding Code to Your ADW +6:03 +Now we have multiple pass fill statements routing back into our build agent. Your codeex, your cloud code, +6:08 +your pi coding agent, whatever your agent harness is. This is the foundation of what it means to build with agents. +6:14 +Now you have three actors in this. Engineers, agents, and raw code. You +6:20 +have to leverage them all in the right location at the right time. Here we're adding a code formatter. It doesn't +6:25 +matter what language you're in. linting your code, formatting your code, type check your code, and then keep scaling +6:31 +up the validation loops to run back into your agents. Once again, you'll see here +6:37 +these conditions is what makes up what is called the loop. But there's a lot more going on here. This is really a +6:44 +workflow of how information travels within a system. Okay, keep scaling it +6:50 +up. What comes next? We can add more code. A very valuable piece of code here +6:55 +is testing your code. So test. Now we take all these results, feed it back +7:00 +into our build agent over and over and over until the results all pass. And +7:05 +that gives us our final engineering review. You'll notice a pattern here. You and I always show up at the ends. +7:12 +These are the two constraints of a gentic engineering. Prompting, also known as planning, and reviewing, also +7:18 +known as validation. If you're a gent engineering at scale properly, you're showing up at the beginning and the end +7:25 +with a few exceptions. Your AI developer workflows start simple like this, but they should continue to grow. Real +7:31 +engineering work looks a lot more complex than this, [music] right? What do we do next? +Scale Your Compute to Scale Your Impact +7:40 +We can scale all of our testing, all of our validation, all of our linting, all of our type checking into a single test +7:47 +agent. So now we're scaling our compute to scale our impact. We're adding compute to add confidence. Now you can +7:54 +imagine we've handed this test agent all the things we want to do to test. And if something goes wrong, we send the +8:01 +context back to the build agent. If it passes, the engineer reviews and then we can ship the deliverable. We can ship +8:08 +the code. All right. So notice a couple themes working here. As you scale up your developer workflows, you add agents +8:14 +and you add code. But what you don't want to add is more engineering effort outside of building the system that +8:21 +builds the system. Let's keep scaling this up. Let's add planning to the workflow. You're very familiar with +8:26 +these ideas, right? We're building workflows. These are all steps that you and I, the engineer, used to take and +8:33 +used to execute ourself, right? We would plan work, we would build the work, we would test the work, we would then have +8:40 +another engineer review the work, and then we would finally ship it into production. All right? It's a developer +8:45 +workflow and all we've done here is added AI to it. The loops is just one +8:50 +piece of it. You can call it loop engineering but it's inaccurate and it's not encapsulating the whole picture. If +8:55 +we have loop engineering, we need to have condition engineering and then we need to have function engineering and then we need to have a word plus +9:02 +engineering for every type of control flow inside of the software development life cycle which is going to go on +9:07 +forever. Okay. So a very popular pattern is to push each one of your agents into +9:13 +their own work tree. This creates isolation. This creates parallelism. This lets you do more work in parallel. +9:19 +And there's a nice side effect here where the agents don't trip over each other. So, guess what we're going to do? +9:24 +We're going to write another prompt. And this time, we're going to write a prompt into a piece of code that's going to +9:31 +build our work trees. All right. So, here we have a deterministic piece of code that's going to kick off multiple +9:37 +work trees based on the prompt. And then we're going to execute several different agents running in line. So we have once +9:44 +again scaled our compute to scale our impact. We have multiple work trees +9:49 +running our plan, build, test, review, merge, ship pipeline, our developer +9:56 +workflow. The workflow you and I used to go through as engineers building by +10:02 +hand. Now we have AI, hence AI developer workflows. And this is really important +10:07 +to think through. This is where you should focus in your engineering time. How can I combine the three actors of +10:14 +value creation, engineers, agents, and code to create workflows that execute +10:20 +large amounts of work on my behalf, on behalf of my company, on behalf of your users and products? That's the name of +10:27 +the game. Okay, so great, we have work trees. Work trees are um like I like to say, a great place to start, not a great +10:34 +place to end. There are a lot of problems with work trees. We can do one better by giving our agents each their +10:40 +own sandbox. Okay? So instead of spinning up work trees, we're now giving every single agent their own computer, +10:47 +right? Their own agent sandbox to operate. Because once you do this, you have full isolation. You yourself can +10:54 +jump into the sandbox to look at the work, look at the result, look at the web page, look at the tests, look at the +11:00 +application, whatever you need to do, do your review. And then of course once all the work comes back in you merge and you +11:06 +ship. So once again notice the three actors of value creation working together. And notice how your ability to +11:14 +create these AI developer workflows is your ability to scale your impact with +11:19 +agents. It's designing these AI developer workflows that is the most value accreative thing an engineer can +11:26 +do. Hence the term I like to say on the channel all the time. You want to be building the system that builds the +11:33 +system. Okay? As you can see here, you'll start to see similarities in these workflows with a lot of work +11:39 +you've seen, a lot of work that you've done, and hopefully work that you're building into your teams, your +11:44 +co-workers, your business, your tools themselves. Okay? We're just getting started, [laughter] right? Uh real work +11:51 +gets more and more complex. And this is the art and science of agentic engineering. So, let's keep scaling it. +The Kanban Queue +12:02 +A very common thing to do as you continue to progress is to set up a conbon board, some type of ticket +12:09 +system. Input comes from all over your organization, right? It comes from support, it comes from product, and it +12:14 +comes from engineers, right? So now things get interesting because now we have a new unit, a new wrapper around +12:20 +our code, right? We have some type of ticketing system. And so once again, like there's this really important delineation that I make inside of +12:28 +tactical agentic coding. And it is this idea of the agentic layer. The agents, +12:33 +the prompts, the skills, the system prompts that wrap your application are +12:39 +the thing to be focused on right now. Because when you put those together with your code, with your system, with your +12:45 +entire team and your organization, you are agentic engineering. Agentic engineering is not just about the +12:51 +agents. Spoiler alert, it's about your team and most importantly your users and putting together the most valuable stack +12:58 +of the actors of value creation. Okay, so conbon board, right? Let's let's jump into this. What does this look like? +13:04 +Okay, so for most teams, your tickets are then analyzed by your engineer who actually knows what's going on and +13:10 +they'll translate that into a mid to low-level prompt that you'll then pass into another full workflow, another +13:17 +agent sandbox. But some advanced teams if you're teaching your organization how to write prompts well enough and as +13:23 +models become more capable uh you can skip your engineer input prompt here right because your engineer's job should +13:29 +be building the system we act on the meta layer we act on the layer that can compound across our organization okay so +13:35 +advanced teams can skip the engineering prompt if this step is done properly all right but so you know this is code right +13:42 +conbon boards it's just code there are no agents there then we enter the meat of our workflow where we run code to +13:48 +move that ticket into planning. Guess what happens next? Our agents take over the pipeline. We'll have a scout agent +13:54 +look for all the code, look for all the tickets, look for all the documentation, look for previous spec files, and then +13:59 +it'll hand that to a plan agent. Right? So, we're splitting up our searching and our planning between two agents here. +14:05 +Once again, scaling compute, scaling impact. And after that happens, you know, plan phase is complete. So, we run +14:11 +code to update our ticket to move context to do some specific work inside of our sandbox. And then of course our +14:17 +build agent kicks off. And you know what happens from here. You've done it a million times yourself. And now with +14:23 +agents, your build agent moves it into testing after it's done. And then your test agent tests, right? This individual +14:30 +loop, which is just one part of the developer workflow, executes until the result passes. And then we're going to +14:37 +run our CI/CD. And guess what can happen here? This can pass or it can fail and +14:42 +go right back to the build agent to resolve the issues. All right. And then we get outside the sandbox. Engineer +14:47 +reviews the code. You know what this looks like now? Fail, pass, ship. Right? So you can see this is much more than +14:54 +just prompt engineering. It's much more than context engineering. It's much more than harness engineering. It's much more than loop engineering. This is about how +15:00 +teams move as an organism with all the actors inside. Okay? And if you're a +15:07 +small solo dev shop, same deal, right? It's about how you and your agents work together with code to generate valuable +15:15 +results. But this isn't the end. The future of engineering is vast. Okay, let's keep pushing this. What happens +15:21 +next? Let's let's imagine another scenario here. Imagine you have a support crisis. Production is down. +Production Goes Down +15:28 +Okay, production has crashed. So, what AI developer workflow do you have planned in your organization right now +15:35 +when production goes down? How are you leveraging engineers, agents, and code +15:40 +to resolve this issue and to stop your business from leaking cash as your production system is down? Let's walk +15:47 +through it, okay? Because we've thought through this, right? We've designed, we've architected the AI developer +15:53 +workflow to account for this situation. Support files a ticket. In our case here, this goes right to Slack. It goes +15:58 +right to Teams, goes right to your communication channel, and one of your cracked engineers picks this up immediately. What do they do? They +16:04 +prompt a scout agent that routes right into a hot fix agent. Your hot fix agent +16:10 +has a specialized set of mental memory. It's an agent expert that knows and is +16:16 +prioritized to get things fixed. It's not doing things the right way. It's not doing things the fancy way. It's not +16:21 +optimizing anything. It's getting the fix out ASAP and nothing else. This is a surgical hotfix agent, a custom agent +16:28 +that you have specialized, that you've templated your engineering into. Now, what happens here? Human in the loop. +16:34 +This is a hot fix. We need to know the solution is going to work. So you put in human effort, right? You use engineering +16:39 +effort to approve or reject. This creates a single loop. All right? If we approve, guess what happens? We're going +16:45 +to build up a bunch of sandboxes to run the solution in parallel. And guess what? We're using multiple sandboxes. I +16:52 +want the first fastest agent that has the solution to win. Okay? Whatever your compute budget is, you'll scale this up. +16:57 +You'll scale this down. If you're in a production system that's complex, you might want three, five, 10 agents +17:02 +running and racing toward a solution in their own agent sandbox, you don't care. You have the compute, you've done the agentic engineering to scale your +17:09 +impact. And guess what happens here? You already know what happens. It runs its individual loop in their sandbox. And +17:15 +then it passes or fails. If it fails, it goes right back to your hot fix agent and to you to resolve. And of course, if +17:21 +it's all successful, you the engineer validate it and you get the hot fix shipped ASAP. Okay. A question for you +17:28 +and your organization. Do you have an agentic workflow for production crashes? Can you get that resolved in record time +17:35 +using the three actors of value creation in the age of agents? Engineers, agents, +17:41 +and code. All three. Okay, this continues to scale and scale and scale. +17:46 +Let's push these workflows further. After some point, what you get is a structure like this. +The Software Factory +17:57 +And this is what really starts turning into a software factory. Okay, you'll see here we have many different types of +18:04 +specialized agent sandbox workflows. Some are for chores, one is for a bug, +18:09 +one is for a feature, one is for this hot fix that we just walked through. And you get the idea here, right? Any +18:15 +specialized AI developer workflow you need can be built and routed to thanks +18:21 +to your routing system. Okay, this is the art and science of agentic +18:26 +engineering, right? This is all of it put together. The loops are just one small piece of this picture. I hope you +18:32 +can see that. Now, in all this is a great level of prompt context harness +18:38 +engineering. There are a million ways to do this. There are a million different multi- aent orchestration patterns to +18:45 +build into this. The key here is this. is that you have the right combination +18:51 +at the right time to push engineering work through end to end with agents with +18:57 +code with engineers. Okay, I know I'm repeating myself. I'm doing it on purpose. Most success in any domain is +19:04 +about doing a few things and saying a few things and focusing on a few things over and over and over. Let's walk +19:11 +through a full software factory. You can imagine how this looks, right? Let's keep with a conbon ticket example. Now, +19:18 +anyone can file a ticket. This is a feature. This is a bug. This is a chore. Advanced teams are going to skip wasting +19:24 +engineering time transferring your conbon ticket into a low-level or mid-level engineering breakdown of what +19:31 +needs to happen. Advanced teams are going to go right to kicking off a software factory. The moment your conbon ticket lands, once the factory starts, +19:37 +it's going to mark that ticket in progress and move it. And now we have a factory router agent. This could just be +19:43 +a simple LLM call. This could be some deterministic code. The exact nodes are +19:48 +up to you to decide, but you get the idea here. I'm going to throw a factory agent here to intake the results. Do a +19:55 +quick look at the codebase, understand what AI developer workflow we need to execute for the system. First though, +20:01 +we're going to set up a sandbox. We're not limiting our agents anymore. We know that agents are going to continue to +20:07 +expand. This is what the CPU crunch is all about. CPUs are getting wiped off the board outside of scaling RL and +20:14 +other ML engineering related work. Agent sandboxes are going to, I can guarantee you this, be the majority of computers +20:20 +out there in the world. You and I will be using fewer and fewer devices while our agents continue to scale up and use +20:25 +more sandboxes. Okay, but set up the sandbox. After that, our agent has already decided what type of workflow we +20:31 +need to get the job done at the best price, at the best performance, and at the right speed. Because as you likely +20:37 +know, you're not going to run your hot fix AI developer workflow or your feature AI developer workflow where +20:43 +you're scaling out your very best agents. Maybe your build agent is a workhorse model, but your planner and +20:48 +your scouters are going to be state-of-the-art model so nothing gets missed. Of course, there's a whole slew of multi- aent orchestration work that +20:55 +can happen here. But the whole point is you're not going to deploy your heavy AI developer workflows for a chore, right? +21:00 +for your chore. Throw a single agent at this with a workhorse model, maybe even a lightweight model. Build it, run the +21:06 +lint, run the CI/CD, engineer reviews it, and ship it out. We'll talk about ZTE in a second, but the best teams are +21:12 +going to start dropping off engineering review because they've built the best system possible that they know is going +21:18 +to execute for them. But every single unique workflow is unique for a reason, +21:24 +right? There are multiple workflows you want to build out here, multiple AI developer workflows you should be building out, not just one. I'll give my +21:30 +recommendation some really, really great practices you can use when building these out in a moment here. But the +21:36 +general rule of thumb is just to start simple. Once you start scaling this up, what you're going to end up with is a +21:41 +software factory. A software factory that can operate your application as +21:46 +well. And if you're doing it right, better than you and your engineering team. This is why all your effort, all +21:52 +of your effort goes into this. Now, the agentic layer, right? This is the al the +21:57 +agentic layer, not the app layer. The app layer is for your agents. The the +22:03 +best engineering teams never touch the product themselves. Okay, I know this might be like controversial. Some +22:09 +engineers are going to hate hearing this, but the best teams are doing meta work on the agentic layer. They're +22:16 +building the system that builds the system. That is the central thesis inside of tactical agentic coding. +22:22 +Thousands of engineers know that and you're going to figure it out too sooner or later. Okay, that doesn't mean you can't jump into the app to do work. But +22:29 +when you have a successful product scaled with users, the name of the game is this. Building a software factory +22:37 +that operates everything better than you alone could, better than code alone could, and better than agents alone +22:44 +could. Right? Three actors of value creation, agents, engineers, code. Where does that all lead us? It leads us to +22:50 +the simple conclusion that it's not a loop you're after. It's an AI developer workflow. Okay, you might be, you know, +22:56 +listening to this and thinking, but you you drew a million loops. Like, isn't this a loop? Fine. If you want to call +23:02 +it a loop, I don't really care. I think a loop is too constrained. If you're going to call it a loop, we're going to need if engineer, we're going to need +23:09 +throw engineering. We're going to need exception engineering, right? We're going to need to name all these things engineering. This is a developer +23:14 +workflow. This used to be what engineers did. Engineers used to decide if something was a chore, if something was +23:20 +a bug. We used to write the plan, we used to execute it, so on and so forth. But now we have a new tool and that's +23:26 +all it is. It's a new tool. We have agents to work with that gives us AI +23:32 +developer workflows. Okay. So at the highest levels of agentic engineering, you're building software factories that +23:39 +execute the right work and the right combination of engineers, agents, and code across your organization. Once you +23:45 +really start to scale it up, you're going to add your other teammates, right? Your other team members from other cross cutting concerns inside of +23:52 +your business. But at the core of it, the engineers are responsible for the code. Okay? I think a lot of orgs are +23:58 +going to have a a problem with this once they start scaling in and adding other team members, right? Especially ones +24:04 +that can't write clear tickets for the life of them. You've seen this a million times, right? It's the most painful +24:09 +thing when your product manager, your your CTO, your your tech lead [laughter] +24:14 +just writes a ticket and you have to translate it, right? So there's there's a lot of like, you know, people +24:19 +organizational level work to be done here. But you at the end of the day, you know, you the engineer plus the agents +24:25 +plus the code making up the AI developer workflow. This is what it's all about. This is where value is going to be +24:31 +created at absurd levels, at absurd scales. Because once you get this right, +24:37 +here's the dirty secret of all software, right? You already know it. Once you get this right, you set up the right +24:43 +guardrails, the right harness, right? Again, prompt, context, harness engineering, all of it. Once you do this +24:48 +right, you have a repeatable workflow that you can run tens, hundreds, and thousands of times, delivering +24:54 +consistent results to you over and over and over again if you template your +25:00 +engineering into the fabric of your AI developer workflows. Okay? And so I've +25:05 +been pushing against out of the box agents for a long time. Um, you know, specialization is the name of the game. +25:11 +What is a product? What is a company? Right? Unless you're a big tech giant, like a product in a company is a a set +25:18 +of people in technology that solve a specific problem for a specific avatar for a specific user for a specific +25:24 +customer. By very definition is specialization, right? Your expertise is +25:30 +the most valuable thing you have now. And you can template that into your engineering. You can template that into +25:36 +your AI developer workflows. All right, this is the greatest leverage point of agentic coding. It's building out these +25:43 +full AI developer workflows that puts it all together. Okay, and so you know once again we are pushing away from vibe +25:51 +coding. This is not vibe coding. Vibe coding is not knowing how the system works and it's not looking at how the +25:56 +system works. Okay, agentic engineering is knowing your system works so well you don't have to look. And that is because +26:03 +you the engineer have moved up a layer. You're meta-engineering. You're compounding an advantage by optimizing +26:10 +the three actors of agentic engineering engineer code agents into the right +26:16 +developer workflow at the right time at the right performance at the right price with the right speed. And after time +26:22 +you'll realize something really important is that you'll be building AI developer workflows into your products +26:28 +for your customers right with your customers as nodes and then as mentioned with your companies every user that can +26:35 +prompt into the system and receive results out the system right you have to design this system it's just another +How to Build Great AI Developer Workflows +26:40 +system +26:45 +so I've written hundreds and probably thousands of these AI developer workflows by now. So, let me give you +26:50 +the oil of everything I've learned so far with what I've seen and what I've recommended to engineers as they're +26:56 +building out their ADWs. Um, first off, keep it simple. When you start building these out, start with the simplest +27:02 +workflow you can think of, right? And typically that looks something like this, right? After you get an agent +27:07 +running, you prompt back and forth and you're babysitting your agent. Everyone knows what this looks like. Just let it lent your code. You know, to be clear, +27:13 +so that you can really feel this. Separate this out. I'm not saying write a skill, have your agent build, and then +27:19 +at the bottom of the skill, run lint. Separate this out. Use an agent SDK, run +27:24 +a build agent, do work, and then run a llinter. And when the llinter fails, pass that back into the build agent with +27:30 +the same session ID. You have to separate your code and your agents. Otherwise, you just have an agent +27:36 +calling code. That's not what we want. We want separation of concerns all the way through. If that doesn't make sense +27:42 +to you right now, don't worry. It'll make sense once you start building it. This is not a big skill where you run a +27:48 +hundred different nodes of workflows. There are massive testing, massive validation problems with doing that. And +27:54 +then what do you do after that? You add a couple nodes, right? Start solving real problems. Run your type checker, +28:00 +run your llinter. If things go wrong, funnel it back into your build agent. What you'll notice here is that you're +28:05 +starting to build a larger unit, a larger system that operates without you. +28:10 +You show the beginning and the end. the two constraints of agent coding, planning and reviewing, and your system +28:16 +does everything else. Okay? And then once you get to a certain point, you'll start separating out your agents. You'll +28:21 +start specializing your agents. Maybe you want to separate your front end and your back end. Maybe you want building +28:26 +and testing. Again, the key here is just that you separate the context out so that your context can move between +28:33 +individual agents and code. When you're starting, remember KISS, keep it simple, stupid. You can absolutely start with +28:40 +pure skill-based workflows where it's all one skill outside of the prompt and the review. But as soon as you start +28:47 +productionizing, as soon as you run to get serious about your AWS, you must separate code out of the skills because +28:53 +that's still your agent running it, right? You have to be super super clear about those steps so that you can set up +28:58 +the proper guard rails and information flows in your AI developer workflows. My next really big piece of advice here is +Do It by Hand First +29:04 +design your ADWs by doing the work yourself first. For a lot of engineers, this will sound insanely painful, but +29:11 +you can like, you know, use your agent in the terminal. Run the build workflow. Do the testing, right? You can still use +29:17 +your agent for that. I'm not saying do it by hand. That would be a waste of time now. But what I am saying is whatever workflow you're setting up, run +29:23 +it end to end. Step into each node yourself. run the pass, run the condition, watch the functions get +29:30 +executed, do the review, and then do the ship to production and then start writing this all as a combination of +29:37 +agents, engineers, and code. And I recommend you take something like mermaid. And you know, by the way, this is like a adaptation of mermaid diagram. +29:45 +I had an agent create using a plan build test AI developer workflow in one shot. I created a animated application which +29:52 +is of course based on a mermaid diagram. Okay, so shout out to mermaid. Shout out to mermaid.live. But that's my second +29:58 +piece of advice, right? Walk through it all yourself first. Sit down pencil and a piece of paper or use mermaid or use +30:04 +whatever. Really sit down and like write out your workflow. And then lastly, make sure you're not just using agents, +Make Sure You're Not Just Using Agents +30:11 +right? Use agents and code. As I mentioned, you can always start with agents and skills, but as soon as you +30:18 +start hitting production, as soon as you want to get serious, move some of that skill work into code. This is not just +30:23 +about token cost. This is about performance, reliability, and speed. Again, everyone in their AI psychosis +30:28 +has like forgotten that speed costs zero tokens. There's no hallucination. It +30:34 +does the exact same thing every time. And it literally runs at the speed of light. So, don't overleverage on agents. +30:41 +Okay? Balance it out with actual code, right? Code execution. And yes, there's +30:46 +information orchestration. There is this is what context engineering is. You're going to need a place for all the +30:52 +results in between each step. Yes, it's going to take some time. Yes, it's going to be a little knowing. Yes, during the +30:57 +process, you'll wonder, I should just throw this all in the skill. You'll be wrong down the road. I can guarantee you that. I've been there. Don't waste your +31:04 +time doing other engineers have already done wrong. Separate it out as you scale this. Okay, so that's the big +31:09 +third tip. Use agents and code. Okay, because agents plus code beats either +31:15 +alone, especially when you start really scaling these into legitimately large AI +31:20 +developer workflows that do serious work for you and your organization. Why? Because you're going to need to test +31:26 +this node. You're going to need to test plan into build. You're going to need to test plan into build and to update the +31:32 +status and to testing and to fail. This is all still a system you the engineer are responsible for. So keep using great +31:39 +classic engineering patterns, isolatable, decoupled, single interface, right? All that stuff matters probably +31:47 +even more, right? It matters even more now because once you do it right and you set up your AI developer workflow, it +31:52 +gets multiplied hundreds and thousands of times and your agents plus your code can drive the outcomes for you. Okay? +31:59 +So, you know, let's step away from the vibes a little bit and let's step out away from the AI psychosis a little bit +32:04 +because if we're going to do serious agentic engineering, you need to know what's going to happen in your system. +Tactical Agentic Coding Pitch +32:10 +So, if you made it to the end here, I want to just say thank you for trusting me. For everyone that's been with the channel for a while, for years now, you +32:16 +know, big shout out to you. I appreciate you trusting me and following along this massive journey of Agentic Engineering +32:21 +that we're on. Um, if you want more, I recommend you check out agenticengineer.com, specifically +32:27 +tactical agentic coding. As I mentioned, I've been pretty early to a lot of these ideas. In tactical agent coding, you're +32:34 +going to hear a lot of what I just said really broken down step by step across eight lessons and then six additional +32:41 +upgradable lessons if you're interested. Okay, so the big idea here is AI developer workflows. It's building +32:47 +systems that build systems. We're not touching the application layer anymore. We're touching the agentic system, the +32:53 +agentic layer that builds it on our behalf. Okay? So, if you want to pay to play, you want to get a big advantage +32:59 +that again thousands of engineers that you know of and have heard of at companies you know the names of, they +33:05 +are in here and they have gotten the advantage and they are getting the advantage, right? It's tactical agent coding is the first eight lessons you +33:11 +can upgrade to agentic horizon to get some upgradeable ideas. really big idea there is of course multi- aent +33:16 +orchestration but agent experts is turning out to be a massively banger idea a massively important idea for +33:23 +engineering in the age of agents if you want to build true specialists that outperform out of the box agent anyway +33:29 +lots more in there's a very clear 30-day refund before you start lesson 4. So if +33:34 +you don't like my style or you're not getting the core of it it's fine I don't want you in here if you don't want to be +33:39 +30-day refund before you start lesson 4. This is going to be linked in the description for you. Also, I recommend if you vibe with the ideas here, if you +33:46 +understand the ideas and you don't want to jump in the tactical agent coding right away, check out this blog. I'll +33:51 +link in the description as well, thinking in threads. It covers a lot of the same ideas we've been discussing 99% +33:58 +of everything I do here on this channel. It's all free. It's out there for you to understand and master agentic +34:04 +engineering. If you made it to the end, do me a favor, like this video, leave a comment, and share it with your coworker +34:09 +before your competition sends it to theirs. You know where to find me every single Monday. Stay focused and keep +34:16 +building. diff --git a/plugins/os-sdlc/.claude-plugin/plugin.json b/plugins/os-sdlc/.claude-plugin/plugin.json new file mode 100644 index 0000000..59fcf22 --- /dev/null +++ b/plugins/os-sdlc/.claude-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "os-sdlc", + "version": "0.1.0", + "description": "Harness-driven software development lifecycle for cc-os: grill/wayfinder/to-spec/to-tickets/implement/review, adapted from Matt Pocock's skill lifecycle and Delta Refinery's multi-level pipeline, wired into os-backlog and os-adr." +} diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md new file mode 100644 index 0000000..cada49e --- /dev/null +++ b/plugins/os-sdlc/OVERVIEW.md @@ -0,0 +1,127 @@ +# os-sdlc — overview (launching point, v0.1) + +Status: scaffold only. No skills/agents/hooks/scripts are implemented yet — this +document exists to anchor a follow-up brainstorming session, not to lock a design. + +## Why this plugin exists + +Matt Pocock (mattpocock/skills) shipped a v1.1 lifecycle update (2026-07-14) that +turned his skill set from a planning tool into a full grill → to-spec → to-tickets → +implement → code-review → commit pipeline. Separately, `~/dev/delta-refinery` runs a +heavier, DB-backed, multi-level pipeline (System Design → Behavioral Design → +Architecture → Slicer → Requirements) with named agent roles per level and a +Pre/Post/Handoff pattern for resumable multi-agent work. + +`os-sdlc` is where cc-os adapts the good parts of both — Matt's lightweight linear +lifecycle and Delta Refinery's structured multi-level handoff discipline — into the +existing os-* family, wired to `os-backlog` (tickets/tracker) and `os-adr` (decision +gate), rather than reinventing either. See +[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md) +for why this is a plugin inside cc-os rather than a separate `cc-sdlc` marketplace. + +## Scope: not just skills + +Unlike most current cc-os plugins, `os-sdlc` is expected to carry all of: +- **skills/** — the lifecycle verbs (`review` is the first: cherry-picks Matt's + standards-conformance + spec-fidelity + Fowler refactor-smell axes into a new + `/os-sdlc:review`, coexisting with the existing generic `/code-review`). +- **agents/** — named roles for pipeline stages, in the spirit of Delta Refinery's + per-level agent rosters, sized down to what a lightweight harness actually needs. +- **hooks/** — session/state wiring where a deterministic check beats a skill. +- **reference/** — general best-practice material by language/framework/pattern that + pipeline stages can pull from (not client- or project-specific — that stays in the + vault). +- **scripts/** — mechanical CLI tooling supporting the above (candidate for the + ADR-0025 lib/+bin/ Ruby structure once real logic exists). + +## Working philosophy this plugin should encode + +Carried over verbatim from the brainstorming that led here, because it's the design +target, not just a preference: + +- **Draft-then-refine over get-it-perfect-up-front.** Autoresearch-style loop: draft + an idea, implement a first pass, audit process and outcome, hypothesize an + improvement, iterate. Applies to both the artifacts os-sdlc produces (specs, + tickets, code) and to os-sdlc's own design. +- **Goal is throughput at trust, not just automation.** The target is being able to + automate large chunks of the dev process for big upcoming projects — "move at the + speed of thought" — which requires the pipeline to be trustworthy enough at each + stage that skipping human review of that stage is safe, not just fast. +- **Composability with the rest of cc-os is a hard constraint**, not a nice-to-have: + os-sdlc must interoperate with `os-backlog` (tickets), `os-adr` (decisions), + `os-vault` (cross-project knowledge) — ADR-023's "os-* plugins cooperate" bet + applies here directly. + +## Known inputs for the follow-up brainstorming session + +- Matt Pocock v1.1 lifecycle notes: `docs/matt-pocock-skills-v1.1-notes.md`. +- Delta Refinery structure (facts gathered this session, not yet written up as a + standalone doc): 5-level `PipelineRunner`/`PipelineOrchestrator`, per-level agent + rosters under `.claude/agents/{prd,functional_spec,technical_spec,requirements}/`, + intra-level in-memory `Handoff` + inter-level DB-persisted `Artifact#structured_content` + for resumability, two composition roots (`HeadwatersComposition` full pipeline vs. + `ProductionComposition` requirement-level-only). +- Existing cc-os pieces this must integrate with: `os-backlog` (capture/list/route), + `os-adr` (find/create/init/migrate), `os-vault` (query/write/onboard-project). +- Open question carried into the brainstorm: how much of Delta Refinery's + resumable-handoff machinery is worth adopting now vs. deferred until a concrete + multi-session pipeline actually needs it (avoid building it ahead of a real need). + +## ADW taxonomy input (2026-07-14 session) + +Cross-project methodology reference, not repo-specific: see the vault note +`agentic-sdlc-ai-developer-workflow-taxonomy.md` (SecondBrain) — a taxonomy of AI Developer +Workflow (ADW) structures from IndyDevDan's "Forget Loop Engineering" video (mermaid diagrams +included, with `[dan]`/`[jrs]` provenance tags separating his claims from cc-os-specific +extrapolation). Read it before designing os-sdlc's pipeline shape; the plan below is the +repo-specific slice of that broader taxonomy. + +Three actors of value creation apply directly to os-sdlc's component design: **code** +(deterministic, free, most reliable — lint/format/test/CI/ticket-state transitions), +**engineer** (the two fixed constraints: prompting/planning at the start, reviewing at the +end), **agent** (judgment work: planning, building, scouting). Every os-sdlc pipeline stage +should be built by first asking which of the three actors it actually needs — don't default +to "agent" for something code or a human gate should own. + +## First-iteration build plan: a single tracer-bullet ADW + +Per the vault note's escalation ladder, and per standing tracer-bullet convention, the first +build target is the smallest complete loop, not the software factory. Scope: + +**One worktree, one pipeline**: `ticket intake → build agent → lint/format/test (hooks) → +engineer review → ship`. Sandboxes, N-way worktree fan-out, the hotfix ADW, and the software +factory router are explicitly deferred — documented in the vault note, not built here. + +Step by step: + +1. **Ticket intake** (code, not agent). Reuse `os-backlog` as the trigger: a card moving to + `Doing` (or a linked Forgejo issue via `/to-tickets`) is the pipeline's entry point. No new + ticketing system — os-sdlc consumes os-backlog's state, per ADR-0037's composability + constraint. +2. **Build agent** (agent, minimal tools). New `os-sdlc` agent definition: system prompt scoped + to "write/modify code to satisfy the spec," tool grants limited to `Read`/`Write`(/`Edit`) — + no `Bash`. It cannot run tests or linting itself; it only ever sees pass/fail feedback handed + back to it. +3. **Lint/format/test gate** (code, via hooks — delta-refinery-style Pre/Post/Handoff, not a + skill-embedded step). A `PostToolUse`-style hook (or a small script the pipeline invokes + between agent turns) runs the project's lint/format/test commands after each build-agent + turn. On failure, the failing output is fed back into the *same* build-agent session as the + next turn's context (per Dan's separation-of-concerns principle). On pass, advance. +4. **Engineer review** (human gate). Standard PR/diff review — no change from how review works + today; the pipeline's job is to get a clean, tested diff in front of the engineer, not to + replace this gate. +5. **Ship** (code). Merge + whatever this repo's existing deploy path is — os-sdlc does not + own deploy; it hands off a mergeable, reviewed change. + +Each step above should be walked by hand first (per Dan's second tip) before being wired into +skills/hooks/agents — run the lint/test loop manually against a real small change, confirm the +feedback-loop shape works, *then* automate it. + +## Not decided yet (do not assume in implementation) + +- Which of Matt's skills get adopted as-is vs. adapted vs. skipped, beyond `review`. +- Whether `implement` is adopted as a thin router as-is, or redesigned as a + Delta-Refinery-style level with named sub-roles. +- Whether `wayfinder` (multi-issue planning for big-plan decomposition) subsumes or + sits alongside a Delta-Refinery-style level structure. +- Any hook or agent definitions — none exist yet.