WEBVTT

00:00:00.000 --> 00:00:06.640
Today, we're looking at one of the best AI coding frameworks on planet Earth. It's a spectrum of tool called OpenSpec,

00:00:06.640 --> 00:00:47.545
and it solves some of the biggest problems that I have faced with other vibe coding frameworks and plug ins and tools. So if you've never used it before and you're tired of screaming into the void as ClaudeCode doesn't do what you said to do for the millionth time, well, you clicked on the right video. And if you have used it before, they've recently added a new expanded workflow, which we will take a look at later. So really quickly, where does this tool sit in the ecosystem of all of these different tools that we have like, Opera and GitHub SpecKit and BMAT and all of these other things? I think these tools kind of work out into like roughly three different categories. Now the first category, which this one falls into, I would consider like spec driven tools.

00:00:47.705 --> 00:01:08.090
So these are gonna be things like GitHub spec kit and obviously open spec, which we are looking at now, where the spec that you create is the primary artifact that drives everything. And so a lot of time is typically spent making sure you're aligned on exactly what you are going to build, and then everything typically follows through nicely from there.

00:01:08.250 --> 00:01:20.365
So the mental model is mostly the human is orchestrating the thing, but the agent is assisting. I personally think this is the best approach if you are a vibe coder or if you're new to AI coding in general,

00:01:20.685 --> 00:01:30.530
because it forces you to get really clear on what it is exactly that you are building and what it needs to do. The second category I would call software development life cycle enforcement.

00:01:30.610 --> 00:01:32.610
So these are things like agent skills,

00:01:32.770 --> 00:01:34.210
over superpowers,

00:01:34.370 --> 00:01:35.730
and compound engineering,

00:01:35.890 --> 00:01:45.385
where, yes, they have certain workflows that they move you through. But the real value in these tools from my perspective is that they enforce best practices and discipline

00:01:45.465 --> 00:01:52.425
onto the actual coding process. So for example, with Obra, something like the test driven development, their red green refactor

00:01:52.750 --> 00:02:03.550
is a really strong thing to do anytime you're gonna build something. And that is not something, for example, that's gonna be built in necessarily to these other tools. And so the third group I would call like the more autonomous

00:02:03.550 --> 00:02:04.350
pipeline.

00:02:04.430 --> 00:02:08.765
And these are where we tend to see tools like bMAD, for example, or get shit done,

00:02:09.005 --> 00:02:17.965
where there's a lot of tooling around, like you being able to define something and then literally walk away and come back and, hey, now it's built something from you without, like, necessarily a ton of

00:02:18.205 --> 00:02:19.005
intervention.

00:02:19.085 --> 00:02:22.125
So now, obviously, there's crossover between a lot of these categories,

00:02:22.205 --> 00:02:33.780
but what we are gonna be looking at today is open spec and how it works. So what we're gonna be doing in this video is solving a problem that I hear from a lot of people, especially in my free group and my pay group, but also in the comments on my videos,

00:02:34.020 --> 00:02:44.005
which is you get this like first version of something like this, and you end up thinking like, this is kind of ugly and it's not really looking like what I want it to look like, but you've spent a lot of work building

00:02:44.005 --> 00:03:19.855
things, and you really wanna make it pop. And so in this case, I went into Claude design and I spent a little bit of time going through and trying to build things out so that it looks a lot more professional and is something I would actually want to use. So for example, this is what the recipe page looks like right now, and this is ideally what it would end up looking like. And so we're gonna try to use a spec driven development tool to bridge this gap and build all of these screens out step by step. And so something I'm really big on is that you can change skills together. Like, just because you're using one of these doesn't mean you can't use the others. So I'm still gonna use Obra's

00:03:20.030 --> 00:03:22.430
working with Git work trees skill

00:03:22.430 --> 00:03:51.250
in order to spin up this work tree, run all of my tests, and make sure we have a clean baseline before we start. So to get this thing working, it's pretty simple. All you need to do is install the package via this command. Then And you come down, move into your project and just type in open spec in it, choose your environment, and then from there you are ready to go. So one of the things that's really cool that I like about this library is they have this onboarding skill. So if you're new to this and this is gonna be the first time using it and you want it to kind of guide you through the process, if you use this onboard command,

00:03:51.330 --> 00:03:54.450
it's gonna actually take you through building your first feature

00:03:54.610 --> 00:04:11.335
with this system. But for purposes of showing you all the steps and how we're gonna use them, I'm gonna run this thing manually. I'm gonna do is I'm gonna hop back into Claw Design and I'm just gonna copy the command that they give you to allow Claw Code to fetch these designs. And then I'm gonna come through and I'm gonna run the first command which is explore.

00:04:11.335 --> 00:04:32.625
So I'm gonna kick this thing off and then we can chat about it. So like most good libraries, it has this optional exploration phase where you can actually think about the ideas before you commit to like exactly how you wanna move through and do it. And so the thing that I really like is you're not locked into like some very specific way of doing things. And with a lot of other tools,

00:04:32.785 --> 00:04:38.145
that's what happens. Like, they have their opinionated approach to how you should move through and do exploration,

00:04:38.385 --> 00:04:40.305
and that gets tied like very

00:04:40.960 --> 00:04:45.120
specifically to the rest of the process. And so there's not like a ton of flexibility

00:04:45.120 --> 00:04:47.360
in being able to use those things sometimes.

00:04:47.680 --> 00:05:10.280
But you can call this command at really any point in the process when you want to dive deeper into what you're about to change. And so this is a nice benefit over something like SpecKit that kind of assumes that you're gonna hop in directly to the spec and like know the thing that you want to build. It has this opportunity for you to really like hash that thing out ahead of time. So if you've used other libraries like compound engineering,

00:05:10.360 --> 00:05:12.040
they have that ideate function.

00:05:12.200 --> 00:05:15.480
This is like kind of similar, but again, a little bit more flexible.

00:05:15.640 --> 00:05:25.255
So once it's read through all of that context, it's gonna start like reasoning about like what we asked for. And so in this case, there are a few different ambiguities that we need to go through and answer

00:05:25.415 --> 00:05:28.775
because we're completely changing the established

00:05:28.775 --> 00:05:32.855
design system that we have documented inside of design.markdown,

00:05:33.015 --> 00:05:36.720
and that gets referenced to be used in agents.markdown.

00:05:36.880 --> 00:05:39.760
So all of those things need to be updated obviously.

00:05:39.840 --> 00:05:44.400
And then we're gonna have to also change, like, the structure of the repo because

00:05:44.640 --> 00:05:47.920
based on the information architecture that's in the new designs,

00:05:48.000 --> 00:06:09.520
that's not gonna map very cleanly onto what we have. So there's a good amount of work that's gonna need to be done. I pasted in a little bit of extra context that it needed, and now it is working on clarifying pieces of the plan. And one thing that I really like about this, it will flag things that we need to be aware of before we move forward. And so this process is really valuable because too many people tend to jump straight into,

00:06:09.680 --> 00:06:15.600
like, trying to build the thing. And what that means is that any of these assumptions that are surfacing as we have this conversation,

00:06:15.840 --> 00:06:28.955
the language model's just gonna decide what to do at the time of building the thing, and then you might not be happy with the output. So this explore features are really nice way to sidestep those problems without like a ton of ceremony and processes

00:06:29.195 --> 00:06:46.770
that we tend to have in other tools like SpecKit or BMAD or some of those other systems. But what do we from here? Once we have this fully explored, the next step is to generate a proposal. And so what you're gonna get out the other side is this proposal markdown file, a system design markdown file,

00:06:46.930 --> 00:06:53.405
and then your task list. So in this design system file, we're gonna get a few different things. Number one are gonna be like the primary

00:06:53.485 --> 00:06:55.085
architecture decisions.

00:06:55.245 --> 00:07:00.445
So for example, in this case for this project, how are we gonna migrate over all of the tokens

00:07:00.605 --> 00:07:05.010
for the design system? How are we gonna actually like build these components

00:07:05.170 --> 00:07:25.375
inside of our system? Because they're obviously different from what was inside of cloud design. How is our like app routing and like the actual architecture of the like the app itself going to change? So we get a bunch of cool details like that. Then the proposal is more about like, well, what is going to actually change inside of this project? So for example, design system migration,

00:07:25.615 --> 00:07:27.215
building out the new screens,

00:07:27.455 --> 00:07:29.455
building out the new component library,

00:07:29.615 --> 00:07:41.760
making sure that we're keeping note of how our data models and our APIs are going to need to change based on the new UI that we're building. Because I told it that I didn't wanna do all the back end changes right now. Right? So it's like a very clear

00:07:42.435 --> 00:08:11.040
change log of like what exactly are we intending to change with this spec. And then we get a phase by phase series of actual tasks that need to be done in order to implement this thing. So we're getting the what and the why of what we're doing from the proposal, the how it's going to be done on a high level from the design markdown file, and then we get the implementation steps from the task file. So this convention is awesome because all of the assumptions and all of the decisions are very clearly documented,

00:08:11.345 --> 00:08:22.625
and we have really concrete tasks at each step. And so the last piece of this, we get this new specs directory where for every major chunk of what we need to do. So for example, the bookmarks migration,

00:08:22.625 --> 00:08:27.240
the discovery page, the people that you're following, the actual, like, design system migration,

00:08:27.480 --> 00:08:46.685
each of these gets an individual spec that has very clear scenarios about, like, exactly what needs to be there. Now before we move on to actually, like, apply these changes and show what the work process looks like, One thing that I really love about this tool is that they have this validate function. And so in this case, I wanted to make sure it has an extra pass

00:08:46.765 --> 00:08:52.765
where it is going to actually verify its work using the Chrome browser extension MCP.

00:08:53.060 --> 00:09:02.500
And that's not something that's like built into the process. A lot of these tools, they tend to like functionally describe how something should work, but they do not often

00:09:02.580 --> 00:09:04.500
describe like visually

00:09:04.580 --> 00:09:43.635
how the thing really needs to look. And that becomes a problem if you're trying to migrate a design system from another tool. And so all we asked us to do was to add a step where it has to verify that. And now that it's made this new spec, it's gonna run through and validate it to make sure that we haven't lost any of the critical details inside of our spec that we're gonna be using to actually build this stuff with. So now we're gonna run the final command, which is apply. And then we're just gonna pass in the directory that it gave us for this project or like the identifier for this project, and we are going to let it run. Now one little note, I did boot up Claude with the Chrome flag,

00:09:43.715 --> 00:09:56.490
so that it can actually like interact with the browser as it's going through and verifying its work. Now this process of having like a front end visual check is actually one of the things that is in the Claude

00:09:56.490 --> 00:09:57.930
code creators

00:09:58.170 --> 00:10:01.930
stack of tips that can have some of the biggest improvement

00:10:02.010 --> 00:10:10.905
on what you get out the other side of these types of vibe coding tasks. Alright, guys. So this thing ran through for about two hours straight

00:10:10.985 --> 00:10:11.785
without

00:10:11.785 --> 00:10:37.505
really any intervention taken from me. The only thing I did was at a certain point, I turned on auto mode so that it would stop pausing to ask me questions. So in reality, with those stops in place, this took maybe three or four hours to actually do. But if we had it on auto mode, the actual time, like processing time, it would have taken two hours and eight minutes. And so again, this includes like actually doing all of the work as well as doing the verification

00:10:37.505 --> 00:10:49.040
that we put in place where it was using Chrome to actually look at the screens. And so we haven't seen what this is gonna look like yet, but it should be at least pretty close to our designs.

00:10:49.120 --> 00:11:11.865
So let's go check it out real quick, and then we'll come back and do the final step. So there's a few different things that I specifically wanna look at because they were some of the aspects of the app that was bothering me the most. The first is this discovery page that we have. So we can see it's like a very clear design. We have the sidebar. Obviously, the sidebar needs to be cleaned up a little bit because it didn't do it to spec. But then we have this hero section, what's cooking now. We have these little filter search options.

00:11:12.420 --> 00:11:14.420
Then we have this like kind of hero

00:11:14.580 --> 00:11:23.700
section, which are like updated more recent things. And then it kind of continues through in like a little bit of an editorial way. So if we pop over into

00:11:23.700 --> 00:11:49.860
the screen, it is looking pretty close to that. So I'm on like a very large screen. And so some of like the spacing of how close the sidebar actually is to like this this middle column, that spacing is a little messed up. So we can address those sorts of things. But overall, like this top section, how it's styled, the little details of like having the person's name and what the recipe was, the trending forks, the editorial pick, all of that stuff is,

00:11:50.100 --> 00:11:56.615
uh, pretty spot on. So I'm really happy with that. The other thing that was really bothering me was the user profile page.

00:11:56.855 --> 00:11:59.655
So if we were to click into,

00:12:00.055 --> 00:12:23.690
uh, Ren, for example, before this was like very vanilla, like it it was nothing. And now if we pop in and go look at what the design was supposed to be. So we can see here there's a few things that are off. This is supposed to be like an accent color. Uh, the alignment on like some of these buttons, these should be like roughly the same size. One should be accented. So there's like a few things that we would need to dial in on this. But overall, for doing like such a large scale refactor

00:12:23.835 --> 00:13:11.320
of the design system, it got like very close to what we were asking it to do. Even this recipe page is like a huge update from what was there in the past. Like, I'm very pleased with how it got through like that first version of what we are asking it to do. And again, the specter of an aspect of what we are doing is why it was able to do this so effectively. So it had, like, the clear functional requirements and clear verification steps. And then it also had those reference designs that it knew to go check. So this is great things work, but one of the surprisingly helpful things is how they finish up a feature branch. And that is one of the things that makes this an awesome tool to use. So if we were to come through here now and run the archive command, basically what this does is it's now going to sync all of the different specs

00:13:11.480 --> 00:13:26.395
and the context that was built up and gathered around it with the root source of truth about your app. And that's one of the things that I really love about this library. A lot of people complain about how it's difficult to manage the documentation

00:13:26.395 --> 00:13:39.560
of their app over time, and this is how OpenSpec helps you manage that. So if we were to go look at this OpenSpec folder where all of this lives, you'll notice that all of the work we were doing was inside of this changes

00:13:39.720 --> 00:14:01.295
folder. And so the way this works is that every single, like, net new feature that you have built, in this case, we built out a few of them. So we had, like, this new bookmarks view. We have the discovery page. We had the following page. We had the update to the design system. All of those different things are gonna get their own spec file. And the reason that this is valuable is when a change gets made then in the future,

00:14:01.615 --> 00:14:15.110
we're going to have a persistent source of truth that describes how this thing should actually work. So for example, if we were to come down now and look at the bookmarks spec, we have a very clear set of requirements

00:14:15.305 --> 00:14:18.745
and then, like, user story scenarios that explain,

00:14:18.745 --> 00:14:26.025
like, functionally what should be happening in this area. Now the reason that this is valuable is that down the line, if we were to go make a change

00:14:26.265 --> 00:14:27.305
to our

00:14:27.545 --> 00:14:28.505
bookmarks

00:14:28.505 --> 00:14:50.425
functionality in the app, When we go to then, like, archive that change like we just did, if we've done something that now breaks a critical piece of this spec, it is going to surface that issue and force us to reconcile it there. So we don't get these sort of, like, black swans or things that are just like hidden now inside of our project that we don't realize

00:14:50.585 --> 00:14:56.425
we broke. So again, it forces you to have like this living set of specifications

00:14:56.585 --> 00:15:07.680
for all of the major features of your app. And so after all of that is done, we get this archive folder. And if we were to click into this, anything now that we have worked on, so for example, this design system migration,

00:15:07.840 --> 00:15:16.225
all of that information actually gets stored so that we can always go back and reference it if we need to. So all the tasks we worked on, the proposal,

00:15:16.545 --> 00:15:34.720
how we were gonna make sure there was like visual fidelity in place, all of that stuff is now saved for us so we can always go back and look at it later. So this is the base workflow, but there's three other workflows you can use that solve a lot of problems that you get with other tools. So the first one up is actually two different workflows

00:15:34.720 --> 00:15:38.960
that you use together, and they are new and continue.

00:15:39.040 --> 00:15:45.895
One of the paradigms of this tool that I think really make it stand out compared with others is that it takes an iterative approach to planning.

00:15:45.975 --> 00:15:52.375
Like, you might have some idea, you start planning it out, but then information pops up along the way, and you want to reintegrate

00:15:52.375 --> 00:16:00.050
that information into your plan moving forward. So one of the ways that they solve that is through these two new commands, new and continue.

00:16:00.050 --> 00:16:05.170
So we're gonna kick off this new command and basically we're gonna say now that we have this front end

00:16:05.330 --> 00:16:06.450
change made,

00:16:06.610 --> 00:16:18.135
we need to build out the back end functionality so that the API routes are there, the data models are in place, and everything is good for us to be able to actually, you know, do this thing. And so we're gonna kick off with the new command

00:16:18.295 --> 00:16:27.650
to start moving in that direction. And so what this does is it sets up a shell for us to move through a similar process that we moved through earlier.

00:16:27.810 --> 00:16:32.530
So what we would do to continue through this process now is type in o p s x continue.

00:16:32.530 --> 00:16:37.810
And then if there are any questions that we need to answer based on this, we can put our responses

00:16:37.970 --> 00:17:12.755
in here. So in this case, have two options. Uh, one is I can do one huge change with everything in it. And number two is that I can slice these changes up into more focused changes and then take them piece by piece, where every single change gets its own proposal specs and tasks. Now since this is touching like the back end logic, I really wanna make sure that we don't miss anything important here. So I chose to go through and slice it that way, which means it's gonna take more time, but it's probably gonna be done better. So now in this case, since we have all of these different slices that we're gonna move through, we can run this new command again.

00:17:12.915 --> 00:17:19.250
But in this case, we're saying, well, what do we wanna kick off? Well, in this specific instance, we're trying to work slice by slice.

00:17:19.330 --> 00:17:23.410
And so we're gonna go through that entire process of creating the proposal,

00:17:23.650 --> 00:17:28.610
applying the changes, and archiving them for each of these individual pieces.

00:17:28.850 --> 00:17:34.245
So we can see similar to how we had that scaffolding for this broader plan, we now have the same scaffolding

00:17:34.245 --> 00:17:36.645
for this very specific change.

00:17:36.805 --> 00:17:45.830
So now if we were to come down and run this continue command, what it's gonna do is it's going to draft the proposal. So similar to how earlier we ran that propose command,

00:17:45.910 --> 00:17:57.190
we're now doing that in this step wise fashion. Instead of us having to call the specific command, we are just moving through the process using this continue command. So the difference that we can see now is when we go into this

00:17:57.765 --> 00:18:01.845
specific like change instance for wiring the public profile reads,

00:18:01.925 --> 00:18:22.960
instead of having generated all of those things at once like we did last time, now we have just the proposal piece. And so we could go through, we can read this, we can make sure that we're on the same page. And then from here, if we move through and run the continue command, it's gonna move on and generate the specs. Now the reason that this is really valuable is that earlier on we looked at that explore command.

00:18:23.120 --> 00:18:37.055
So if at any point we're in the middle of doing this and something crops up that we kind of don't know the best way to handle it, we can run the explore command. We can talk through the problem, and then we can integrate that change into whatever stage we're at now.

00:18:37.375 --> 00:18:40.670
So this library is really good at generating the context,

00:18:40.910 --> 00:19:01.835
storing it in a really intelligent way, and then letting you move through to the next stage really easily. So one of the things that's really nice is that if at any point we think we're already good enough with the plan and we just wanted to run through the rest of the stages, we can run this fast forward command. And so this is gonna allow us to go a lot faster, but still remain on rails. Like it's still following the system,

00:19:02.235 --> 00:19:03.835
which is enforcing

00:19:03.835 --> 00:19:15.750
like the best way of doing things and having your spec in place, and then developing from that spec and doing everything that you define there. And so this is very similar to what we were doing in that new and continue paradigm,

00:19:15.750 --> 00:19:18.790
except it's just gonna continue to move through it automatically.

00:19:18.790 --> 00:19:26.125
So this is now complete and that brings us to the final feature which I think is one of the most valuable things about how this library works.

00:19:26.285 --> 00:19:32.765
And that is the sync command. So basically what this does is it helps you keep a running tab of the actual state

00:19:32.845 --> 00:19:38.260
of all of the different features of your apps that you don't need to worry about documentation

00:19:38.260 --> 00:19:46.900
going off the rails and quickly becoming out of date. So if we were to come back into that master specs folder and we were to scroll down now to public profile,

00:19:47.060 --> 00:19:57.495
we can see that it has been updated based on this work. So all of this extra information in here about, like, the requirements and what the database needs to look like and all of those things,

00:19:57.735 --> 00:20:01.175
these are all based on the work that we just did in this change.

00:20:01.255 --> 00:20:05.090
So we already had the public profile spec that existed,

00:20:05.250 --> 00:20:13.410
but now it's been updated with the work that just happened. So anytime we make any change that touches something that already exists,

00:20:13.490 --> 00:20:33.790
we have this built in step that's gonna go back and actually update the documentation so that things never get lost and never fall out of touch with the reality of what is there. And that is a huge value add that you don't get with a lot of other tools natively. So this library is pretty great. And I think for having like a daily driver type of workflow,

00:20:33.870 --> 00:20:35.230
specifically one that

00:20:35.470 --> 00:20:38.670
calls these other plugins like Obra or

00:20:38.830 --> 00:20:43.550
similar libraries in when you need them. For example, with like sub agent execution

00:20:43.710 --> 00:20:44.990
or test driven development,

00:20:45.445 --> 00:20:51.445
this is for sure a new daily driver, especially if you're working on an established project.

00:20:51.445 --> 00:21:00.725
So if you like this video, I'm gonna link to a playlist of other breakdowns of tools like this one that I have done. But that is it for this video. I will see you in the next one.