diff --git a/README.md b/README.md index 759ba57..58ce693 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,2 @@ -# cyberfabric-courses -Cyber Fabric courses +# constructorfabric-courses +Constructor Fabric courses diff --git a/courses/constructor-studio-draft.md b/courses/constructor-studio-draft.md index 095fbd3..60082fb 100644 --- a/courses/constructor-studio-draft.md +++ b/courses/constructor-studio-draft.md @@ -1,8 +1,8 @@ # Constructor Studio Academy - Course Blueprint and Table of Contents > NOTE: These course materials are a draft, generated from the following source repositories: -> - https://github.com/cyberfabric/cyber-constructor (to be renamed `constructor-studio`) -> - https://github.com/cyberfabric/cyber-constructor-kit-sdlc (to be renamed `constructor-studio-kit-sdlc`) +> - https://github.com/constructorfabric/studio +> - https://github.com/constructorfabric/studio-kit-sdlc ## 1. Target Audience, Problem, and Solution @@ -84,7 +84,7 @@ Description: All lessons use the standard Constructor Studio terms and tools: Co - 2.2.2 CLI tool name: `cfs` - 2.2.3 Root skill and activation: `/cf` - 2.2.4 Studio command surface: `/cf-studio` -- 2.2.5 Core workflow commands: `/cf-plan`, `/cf-generate`, `/cf-analyze` +- 2.2.5 Core skills: `/cf-plan`, `/cf-write-docs`, `/cf-coding`, `/cf-explore` - 2.2.6 Kit workflow commands: `/cf-{kit}-{name}` - 2.2.7 Naming practice: choosing the right command form @@ -258,7 +258,7 @@ Description: Learners perform a small but meaningful first run without overloadi #### Lessons and Checkpoints -- 4.6.1 Why first use should often be `/cf-analyze` or `/cf-plan` +- 4.6.1 Why first use should often be `/cf-explore` or `/cf-plan` - 4.6.2 First prompt patterns that work - 4.6.3 Reading the response structure - 4.6.4 Deciding the next action @@ -266,7 +266,7 @@ Description: Learners perform a small but meaningful first run without overloadi ## 5. Operator Track - Daily Workflows -Description: This part teaches the core workflows an operator uses every day: plan, generate, analyze, validate, review, and iterate. +Description: This part teaches the core workflows an operator uses every day: plan, write documents, implement, explore, validate, review, and iterate. ### 5.1 Workflow Selection @@ -275,8 +275,8 @@ Description: Learners learn to choose the right workflow before asking the agent #### Lessons and Checkpoints - 5.1.1 `/cf-plan` for large or risky work -- 5.1.2 `/cf-generate` for creating or changing artifacts and code -- 5.1.3 `/cf-analyze` for validation, review, and inspection +- 5.1.2 `/cf-write-docs` and `/cf-sdlc-doc-*` for creating or changing artifacts +- 5.1.3 `/cf-coding`, `/cf-sdlc-implement`, and review skills for code changes, validation, and inspection - 5.1.4 `/cf-studio` as the broader command surface - 5.1.5 Kit-specific commands with `/cf-{kit}-{name}` - 5.1.6 Checkpoint: choose a workflow for each scenario @@ -294,9 +294,9 @@ Description: This module teaches how to decompose work into phase files and chec - 5.2.5 Execution readiness and validation - 5.2.6 Lab: create a plan for a medium-risk change -### 5.3 Generating Artifacts with `/cf-generate` +### 5.3 Writing Artifacts with `/cf-write-docs` and `/cf-sdlc-doc-*` -Description: Learners create and update structured artifacts using templates, examples, rules, and confirmation gates. The module focuses on bounded generation rather than free-form writing. +Description: Learners create and update structured artifacts using templates, examples, rules, and confirmation gates. The module focuses on bounded document authoring rather than free-form writing. #### Lessons and Checkpoints @@ -320,9 +320,9 @@ Description: This module teaches how code changes are constrained by approved re - 5.4.5 Validation after implementation - 5.4.6 Lab: implement a bounded feature from a spec -### 5.5 Analyzing Artifacts with `/cf-analyze` +### 5.5 Reviewing Artifacts with Dedicated Review Skills -Description: Learners validate artifacts through deterministic gates and semantic review. The module shows why a validator pass alone is not the same as a complete review. +Description: Learners validate artifacts through deterministic gates and semantic review. The module shows why a validator pass alone is not the same as a complete review, and routes review work to dedicated skills such as `/cf-write-docs`, `/cf-sdlc-pr-review`, and `/cf-sdlc-change-impact-analysis`. #### Lessons and Checkpoints @@ -871,8 +871,9 @@ Description: This mapping covers AI coding tool commands and skills. - Root command or skill: `/cf` - Studio surface: `/cf-studio` - Plan workflow: `/cf-plan` -- Generate workflow: `/cf-generate` -- Analyze workflow: `/cf-analyze` +- Document-writing skills: `/cf-write-docs`, `/cf-sdlc-doc-prd`, `/cf-sdlc-doc-design`, `/cf-sdlc-doc-adr` +- Code implementation skills: `/cf-coding`, `/cf-sdlc-implement` +- Review and exploration skills: `/cf-explore`, `/cf-sdlc-pr-review`, `/cf-sdlc-change-impact-analysis` - Kit workflow pattern: `/cf-{kit}-{name}` ### A.3 Course Writing Rules @@ -929,4 +930,4 @@ Description: This path is for technical leads planning rollout across a team or - Complete Part 5 modules 5.1 through 5.6 - Complete Part 6 modules 6.3, 6.4, 6.5, and 6.8 - Complete Part 8: Governance, CI, and Team Adoption -- Review Part 9 certification rubric for internal enablement \ No newline at end of file +- Review Part 9 certification rubric for internal enablement diff --git a/courses/cyberfabric-all-course-content.md b/courses/constructorfabric-all-course-content.md similarity index 89% rename from courses/cyberfabric-all-course-content.md rename to courses/constructorfabric-all-course-content.md index 4f1267c..c4a63e9 100644 --- a/courses/cyberfabric-all-course-content.md +++ b/courses/constructorfabric-all-course-content.md @@ -1,9 +1,9 @@ -# Course orientation: Modern AI-Native software development and the Cyber Fabric Foundation +# Course orientation: Modern AI-Native software development and the Constructor Fabric Foundation -### Module overview +## Module overview This course is about how software development changes in the AI era, -with Cyber Fabric used as a practical open-source implementation of +with Constructor Fabric used as a practical open-source implementation of AI-native software delivery. AI tools can help teams generate code, draft tests, explain unfamiliar @@ -13,7 +13,7 @@ Requirements, architecture, design, validation, deployment, production operations, governance, reusable components, measurement, and feedback all still matter. -Cyber Fabric provides a practical way to understand this broader shift. +Constructor Fabric provides a practical way to understand this broader shift. It shows how a software delivery lifecycle can become more connected, traceable, governed, reusable, and measurable. @@ -27,12 +27,12 @@ verified GitHub contribution or structured participation activity. - LO4: Explain the role, mission, and open-source model of the Cyber Fabric Foundation; -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery. -### Cyber Fabric: connecting the software delivery lifecycle +## Constructor Fabric: connecting the software delivery lifecycle -**Cyber Fabric as a practical implementation of AI-native delivery** +**Constructor Fabric as a practical implementation of AI-native delivery** AI is changing software development because it can now support tasks that previously required more manual effort. Developers and teams can @@ -66,7 +66,7 @@ improving. | May produce plausible output. | Requires output to be checked against intent and constraints. | -Cyber Fabric gives AI-native delivery a practical shape. It shows how +Constructor Fabric gives AI-native delivery a practical shape. It shows how requirements, architecture, design, code, tests, deployment, production signals, reusable components, metrics, and contribution can be connected rather than treated as isolated pieces of work. @@ -85,13 +85,13 @@ matter for delivery. | What production signal shows whether it works? | Connects delivery to real usage and feedback. | -Cyber Fabric is positioned around these lifecycle connections. It is a +Constructor Fabric is positioned around these lifecycle connections. It is a practical implementation of a more connected, governed, and measurable approach to modern software delivery. -The Cyber Fabric Foundation and open-source model +The Constructor Fabric Foundation and open-source model -Cyber Fabric is supported by an open-source foundation model. This +Constructor Fabric is supported by an open-source foundation model. This matters because learners are not only learning about a software delivery approach. They are also learning how an open ecosystem can be inspected, extended, improved, and contributed to. @@ -138,7 +138,7 @@ whether the work is connected to clear requirements, sound design, validation, deployment readiness, operational signals, governance, reusable components, measurement, and feedback.\ \ -Cyber Fabric is introduced as a practical open-source implementation of +Constructor Fabric is introduced as a practical open-source implementation of this broader delivery model. Its value is not limited to one tool or interface. It helps frame software delivery as a connected lifecycle where planning, building, running, validation, reuse, measurement, @@ -151,7 +151,7 @@ improved, and connected from intent to production.   # The AI acceleration gap: Why coding accelerates faster than delivery -### Module overview +## Module overview AI has significantly accelerated code development, but software delivery as a whole has not accelerated at the same rate. In many organizations, @@ -181,10 +181,10 @@ Learning outcomes addressed - LO2: Explain why faster code generation does not automatically mean faster software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Beyond faster coding +## Beyond faster coding How AI changes the coding bottleneck @@ -333,7 +333,7 @@ acceptance criteria, checking architecture consistency, validating security expectations, and ensuring the team can trace production behavior back to the original intent. -### Optional practical activity +## Optional practical activity **LO Alignment: **This activity addresses LO7 by asking learners to apply the AI acceleration gap to a real workflow. It also reinforces @@ -387,7 +387,7 @@ monitoring signal.\ A strong answer should make clear: AI made one step faster, but delivery still depends on intent, fit, review evidence, validation, and feedback. -### Module summary +## Module summary This module focused on the AI acceleration gap: AI has significantly accelerated code development, but software delivery has not accelerated @@ -410,7 +410,7 @@ delivery speed will continue to grow.   # From AI coding to AI-Native software delivery -### Module overview +## Module overview This module moves from the problem to the broader model of modern AI-native software delivery. @@ -442,7 +442,7 @@ Learning outcomes addressed - LO3: Describe the plan-build-run model for AI-native software delivery. -### From AI-Assisted coding to AI-Native delivery +## From AI-Assisted coding to AI-Native delivery AI-assisted coding means using AI tools to support implementation tasks. A developer might ask AI to generate a function, explain a code block, @@ -560,7 +560,7 @@ Better delivery measures include cycle time, review waiting time, deployment frequency, defect rate, incident volume, test quality, rework, bottlenecks, and production feedback. -### Deeper dive: Artifact-backed AI-Native workflows +## Deeper dive: Artifact-backed AI-Native workflows AI-native delivery depends on artifacts that are durable, inspectable, and connected. A prompt can start useful work, but a prompt by itself is @@ -656,7 +656,7 @@ Good artifacts reduce repeated clarification, make AI output easier to evaluate, and help reviewers focus on judgment rather than reconstruction. -### Optional practical activity +## Optional practical activity **LO Alignment: **This activity addresses LO3 by asking learners to define plan, build, and run in their own context. It also addresses LO7 @@ -716,7 +716,7 @@ before asking AI to implement anything: Then decide which parts can be generated by AI, which parts should be checked deterministically, and which parts require human approval. -### Module summary +## Module summary This module moved from the delivery problem to the AI-native delivery model. It clarified that AI-assisted coding and AI-native delivery are @@ -738,25 +738,25 @@ The lasting idea from this module is that AI-native delivery is not governed delivery system that links intent, implementation, validation, production signals, and feedback.   -# Cyber Fabric as the solution: One connected fabric +# Constructor Fabric as the solution: One connected fabric -### Module overview +## Module overview -This module introduces Cyber Fabric as a practical implementation of +This module introduces Constructor Fabric as a practical implementation of AI-native software delivery. The previous modules explained why faster coding does not automatically -improve delivery. This module shows how Cyber Fabric addresses that +improve delivery. This module shows how Constructor Fabric addresses that problem by connecting the software lifecycle across planning, building, running, validation, governance, reuse, measurement, and feedback. -The module explains Cyber Fabric as a connected delivery fabric rather +The module explains Constructor Fabric as a connected delivery fabric rather than only a code-generation tool. It shows how requirements, architecture, design, code, tests, deployment records, production signals, support feedback, and reusable components can be linked into a more coherent delivery flow. -The key message is: Cyber Fabric helps teams move from isolated coding +The key message is: Constructor Fabric helps teams move from isolated coding acceleration to system-level delivery improvement by connecting intent, implementation, validation, operations, and feedback. @@ -765,15 +765,15 @@ Learning outcomes addressed - LO3: Describe the plan-build-run model for AI-native software delivery; -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Cyber Fabric as a connected delivery fabric +## Constructor Fabric as a connected delivery fabric -Cyber Fabric is a connected delivery fabric for AI-Native software +Constructor Fabric is a connected delivery fabric for AI-Native software development. It helps connect the major parts of the software lifecycle so work does not remain scattered across disconnected tools, documents, repositories, tests, deployment records, and production dashboards. @@ -791,14 +791,14 @@ cross-cutting questions: Which requirement does this code implement? Which design decision shaped it? Which tests validate it? Which release introduced the production issue? -Cyber Fabric is designed around these connections. It supports a +Constructor Fabric is designed around these connections. It supports a delivery model where planning, building, running, validation, governance, reuse, measurement, and contribution are part of one connected flow. Orchestration, governance, and reuse -Cyber Fabric adds value in three connected ways: orchestration, +Constructor Fabric adds value in three connected ways: orchestration, governance, and reuse. Orchestration connects the lifecycle. Governance controls how work moves through that lifecycle. Reuse reduces repeated work on common capabilities. @@ -813,7 +813,7 @@ rework, delays, security issues, or operational problems. A team that only has orchestration may see connections but still lack rules. A team that only has governance may enforce checks but still duplicate common components. A team that only has reuse may save effort -but still lack traceability from requirement to production. Cyber Fabric +but still lack traceability from requirement to production. Constructor Fabric brings these ideas together. Example: role-management feature @@ -835,16 +835,16 @@ violations. The release record links the feature to the requirement, implementation, and validation results. Production monitors audit logs, permission errors, and support tickets. -### Deeper dive: Using the GitHub organization as a product map +## Deeper dive: Using the GitHub organization as a product map -Cyber Fabric is easier to understand when the GitHub repositories are +Constructor Fabric is easier to understand when the GitHub repositories are viewed as a product map rather than as a random list of codebases. Each repository represents part of the delivery fabric: governed delivery workflows, analytics, reusable components, UI patterns, documentation, automation, code generation, or contribution support. A practical way to navigate the ecosystem is to group repositories by -the three Cyber Fabric elements. +the three Constructor Fabric elements. 1\. Constructor-oriented repositories help explain governed AI-assisted delivery. Cyber Pilot is the main workflow and repository-context @@ -888,13 +888,13 @@ course goal is practical fluency: understanding why each repository exists, which delivery problem it addresses, and how it fits into the wider fabric. -### Optional practical activity +## Optional practical activity **LO Alignment: **This activity addresses LO7 by asking learners to -place Cyber Fabric in a realistic workflow and diagnose orchestration, +place Constructor Fabric in a realistic workflow and diagnose orchestration, governance, and reuse gaps. -Learners explain where Cyber Fabric would fit in their current +Learners explain where Constructor Fabric would fit in their current toolchain. How to construct your answer @@ -908,23 +908,24 @@ documentation, or monitoring.\ Example: PRs are not linked to requirements, AI-generated code is hard to review, tests do not reflect acceptance criteria, or incidents do not feed back into planning.\ -**3. Cyber Fabric fit**\ +**3. Constructor Fabric fit**\ Choose one:\ - Constructor: traceability, requirements, validation, AI-governed SDLC;\ - Insight: bottlenecks, metrics, AI adoption visibility;\ - Ware: reusable components, UI patterns, platform capabilities.\ **4. What stays in place**\ -Name the existing tools that remain.5. Expected improvement\ +Name the existing tools that remain.\ +**5. Expected improvement**\ State one measurable or observable benefit.\ \ -A strong answer is focused: one workflow, one gap, one Cyber Fabric +A strong answer is focused: one workflow, one gap, one Constructor Fabric entry point, one expected improvement. -### Module summary +## Module summary -This module introduced Cyber Fabric as a practical implementation of -AI-Native software delivery. It positioned Cyber Fabric not as a +This module introduced Constructor Fabric as a practical implementation of +AI-Native software delivery. It positioned Constructor Fabric not as a code-generation tool or product interface, but as a connected delivery fabric for linking planning, building, running, validation, governance, reuse, measurement, contribution, and feedback.\ @@ -937,7 +938,7 @@ code faster but still struggle to validate whether the work matches intent, follows design decisions, deploys safely, or improves based on production evidence.\ \ -The lasting idea from this module is that Cyber Fabric helps shift +The lasting idea from this module is that Constructor Fabric helps shift software delivery from isolated AI-assisted tasks to a connected delivery system where intent, implementation, validation, operations, repositories, and feedback can be governed, traced, reused, measured, @@ -945,7 +946,7 @@ and improved.   # Benefits of a connected AI-Native delivery fabric -### Module overview +## Module overview This module explains the benefits of a connected AI-native delivery fabric. @@ -972,13 +973,13 @@ Learning outcomes addressed - LO2: Explain why faster code generation does not automatically mean faster software delivery; -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Why connection matters +## Why connection matters End-to-end visibility @@ -1014,7 +1015,7 @@ Bottleneck detection shows where work slows down. Reuse reduces repeated work on common capabilities such as billing, identity, access control, notifications, usage metering, audit logging, and integrations. -### Deeper dive: Why connection matters +## Deeper dive: Why connection matters The main module has already introduced the three core benefits of a connected delivery fabric: end-to-end visibility, controlled flows, and @@ -1066,7 +1067,7 @@ evidence. Finally, ask which production or usage signal would tell the team whether the feature worked. If this path is difficult to follow, the delivery fabric is not yet doing its job. -In Cyber Fabric, this idea is easiest to inspect through +In Constructor Fabric, this idea is easiest to inspect through Constructor-oriented examples such as Cyber Pilot. In Cyber Pilot, learners can see how workflows, repository context, and validation are treated as part of the delivery surface. This example shows that @@ -1182,32 +1183,32 @@ A connected delivery fabric also improves onboarding and contribution readiness. When artifacts, examples, validation rules, and repository roles are visible, new contributors can understand where to start and what kind of change is safe to propose. This is especially important in -an open-source ecosystem such as Cyber Fabric, where useful first +an open-source ecosystem such as Constructor Fabric, where useful first contributions may include clearer documentation, better examples, sharper acceptance criteria, or evidence-rich issue reports. This topic is developed further in the participation module. -Where to inspect these ideas in Cyber Fabric +Where to inspect these ideas in Constructor Fabric -If you want to connect this module to the Cyber Fabric GitHub +If you want to connect this module to the Constructor Fabric GitHub repositories, inspect the examples through the benefit you are studying, not alphabetically. - For controlled AI-assisted flows, inspect Cyber Pilot: - https://github.com/cyberfabric/cyber-pilot. Look for workflow, + https://github.com/constructorfabric/cyber-pilot. Look for workflow, context, configuration, generated integration, and validation ideas rather than deep internals. - For continuous acceleration through measurement, inspect Insight: - https://github.com/cyberfabric/insight. Focus on what delivery + https://github.com/constructorfabric/insight. Focus on what delivery questions the data and analytics model is meant to answer. -- For reuse, inspect CyberFabric Core, FrontX, or DNA depending on your +- For reuse, inspect ConstructorFabric Core, FrontX, or DNA depending on your role. These repositories show different ways reusable product, platform, UI, documentation, standards, and generation patterns can support delivery. -### Module summary +## Module summary This module explained the benefits of a connected AI-native delivery fabric. It focused on how connected delivery improves visibility, @@ -1228,14 +1229,14 @@ about speed. It is about building a delivery system where work is visible from intent to operations, governed through clear flows, and improved through evidence, reuse, operational learning, and feedback.   -# The three elements of Cyber Fabric +# The three elements of Constructor Fabric -### Module overview +## Module overview -This module explains the three main elements of Cyber Fabric: Cyber +This module explains the three main elements of Constructor Fabric: Cyber Constructor, Cyber Insight, and Cyber Ware. -Cyber Fabric is modular. It is not one single tool or feature. Each +Constructor Fabric is modular. It is not one single tool or feature. Each element supports a different part of AI-native delivery. Cyber Constructor supports SDLC governance, specifications, traceability, validation, and controlled AI-assisted workflows. Cyber Insight supports @@ -1254,16 +1255,16 @@ delivery. Learning outcomes addressed -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; - LO6: Explain the purpose of Cyber Constructor, Cyber Insight, and Cyber Ware; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Cyber Constructor, Cyber Insight and Cyber Ware +## Cyber Constructor, Cyber Insight and Cyber Ware Cyber Constructor @@ -1310,11 +1311,11 @@ support a connected AI-native delivery system where requirements are governed, delivery outcomes are measured, and common platform capabilities are reused. -### Deeper dive: Technical product orientation to Constructor, Insight, and Ware +## Deeper dive: Technical product orientation to Constructor, Insight, and Ware The main module introduced Cyber Constructor, Cyber Insight, and Cyber Ware. In this Deeper Dive, those three elements become a structured -guide to the Cyber Fabric GitHub organization. The objective is not to +guide to the Constructor Fabric GitHub organization. The objective is not to memorize every repository; it is to understand how the repository landscape expresses the product model, where a technical learner should begin, and how each repository supports AI-native delivery, inspection, @@ -1332,10 +1333,10 @@ How to use this repository guide Do not read the GitHub organization alphabetically. Read it by role in the delivery fabric. To understand governed AI-assisted delivery, start with Cyber Pilot and the SDLC kit if both are visible in the current -Cyber Fabric GitHub organization. To understand measurement, start with +Constructor Fabric GitHub organization. To understand measurement, start with Insight and Insight Front if they are available. To understand reusable platform and UI capability, start with publicly visible Ware-oriented -repositories such as CyberFabric Core and FrontX. For each repository, +repositories such as ConstructorFabric Core and FrontX. For each repository, begin with the README and then inspect the visible guides, workflows, examples, configuration files, validation files, issues, and contribution guidance. @@ -1346,10 +1347,10 @@ Repository map | Area | Repositories | How to use them | |---|---|---| | Constructor core | cyber-pilot, cyber-pilot-kit-sdlc | Inspect these first when you want to understand governed AI-assisted delivery, SDLC artifacts, traceability, validation, and example workflows. | -| Constructor adjunct or reference | cyber-constructor, cyber-pilot | Use these carefully as supporting or historical context unless current documentation shows a direct course use. | +| Constructor adjunct or reference | studio, cyber-pilot | Use these carefully as supporting or historical context unless current documentation shows a direct course use. | | Insight | insight, insight-front | Inspect these when you want to understand delivery analytics, identity resolution, dashboards, bottlenecks, and AI adoption measurement. | -| Ware platform and tooling | cyberware-rust, cyberware-csharp | Inspect these when you want to understand reusable Cyber Ware foundations for enterprise-grade SaaS products, including backend framework and middleware, modern SaaS UI development, and related C# modules or platform components. | -| Ware UI, docs, and standards | cybereare-frontx, DNA | Inspect these when you want to understand UI, development principles, guidelines, and instructions for multi-tenant SaaS platform and application development. | +| Ware platform and tooling | cyberware-rust, constructorfabric-core-csharp | Inspect these when you want to understand reusable Cyber Ware foundations for enterprise-grade SaaS products, including backend framework and middleware, modern SaaS UI development, and related C# modules or platform components. | +| Ware UI, docs, and standards | frontx, DNA | Inspect these when you want to understand UI, development principles, guidelines, and instructions for multi-tenant SaaS platform and application development. | | Product and learning support | website, ai-courses | Use these for product positioning, course-production references,. | @@ -1369,7 +1370,7 @@ Constructor-related material. Cyber Pilot -**Repository: ** +**Repository:** Cyber Pilot formalizes a traceable delivery system to connect requirements, design, plans, and code within AI-assisted workflows. A @@ -1389,7 +1390,7 @@ can be enforced across complex, AI-driven engineering projects. Cyber Pilot SDLC kit -**Repository: **[https://github.com/cyberfabric/cyber-constructor-pilot-kit-sdlc](https://github.com/cyberfabric/cyber-pilot-kit-sdlc) +**Repository:** [https://github.com/constructorfabric/cyber-pilot-kit-sdlc](https://github.com/constructorfabric/cyber-pilot-kit-sdlc) The SDLC kit packages common artifact categories and delivery gates. A typical flow moves from requirement to design to decomposition to @@ -1411,11 +1412,11 @@ The following repositories are useful to know, but they are not the main starting point for most learners. Inspect them later if your role or contribution path points there. -- **cyber-constructor**:  +- **studio**: -- **cyber-pilot-old**:  +- **cyber-pilot-old**:  -- **cyberware-obsidian**:  +- **cyberware-obsidian**:  Practical Constructor learning path @@ -1463,7 +1464,7 @@ without outcome improvement. The value comes from interpretation. Insight -**Repository: **[https://github.com/cyberfabric/cyber-insight](https://github.com/cyberfabric/insight) +**Repository:** [https://github.com/constructorfabric/insight](https://github.com/constructorfabric/insight) Cyber Insight formalizes a medallion data architecture to transform fragmented toolchain events into governed business metrics. A typical @@ -1485,7 +1486,7 @@ monorepo. Insight Front -**Repository: **[https://github.com/cyberfabric/cyber-insight-front](https://github.com/cyberfabric/insight-front) +**Repository:** [https://github.com/constructorfabric/insight-front](https://github.com/constructorfabric/insight-front) Cyber Insight Frontend formalizes a decision intelligence platform for engineering analytics, productivity insights, and team health. A typical @@ -1526,11 +1527,11 @@ delivery and creates inconsistency. Ware asks which capabilities should become reusable so teams can focus more time on differentiated product work. -CyberFabric Core +ConstructorFabric Core -**Repository: **[https://github.com/cyberfabric/cyberware-rust](https://github.com/cyberfabric/cyberfabric-core) +**Repository:** [https://github.com/constructorfabric/constructorfabric-core](https://github.com/constructorfabric/constructorfabric-core) -CyberFabric Core is the main technical anchor for Ware. It should be +ConstructorFabric Core is the main technical anchor for Ware. It should be understood as a secure modular framework and middleware foundation, not as a finished SaaS product. For this course, you do not need to inspect every Rust module. Understand the product idea: Core provides reusable @@ -1545,7 +1546,7 @@ Cargo.toml show the quality and validation posture. FrontX -**Repository: ** +**Repository:** FrontX is the UI development kit anchor. It is relevant because AI-native delivery also applies to user interfaces. AI can generate @@ -1564,7 +1565,7 @@ VALIDATION_REPORT.md DNA -**Repository: ** +**Repository:** DNA provides development norms and architecture guidance. This is important because AI agents and humans both need explicit conventions. @@ -1583,12 +1584,12 @@ depth in the core course. Inspect them when your role, adoption path, or contribution interest connects to them. Do not treat thin, early, placeholder, or legacy repositories as primary technical anchors. -- **website**:  - product +- **website**:  - product positioning and public-facing context -- **ai-courses**:  - courses +- **ai-courses**:  - courses -- **cyberware-csharp**:  - +- **constructorfabric-core-csharp**: - C# reference material or role-specific platform comparison Practical Ware learning path @@ -1615,9 +1616,9 @@ This is the connected fabric idea in practice. AI becomes one participant in a delivery system that can structure work, reuse proven patterns, validate evidence, and learn from outcomes. -### Module summary +## Module summary -This module introduced the three main elements of Cyber Fabric: Cyber +This module introduced the three main elements of Constructor Fabric: Cyber Constructor, Cyber Insight, and Cyber Ware. These elements are modular, but they work together to make AI-native delivery more governed, measurable, and reusable.\ @@ -1633,68 +1634,68 @@ business support modules, operational support modules, platform services, integration engines, development kits, UI patterns, documentation workflows, CLI support, and code-generation resources.\ \ -The lasting idea from this module is that Cyber Fabric is not one +The lasting idea from this module is that Constructor Fabric is not one isolated capability. Constructor governs the work, Insight measures the work, and Ware provides reusable building blocks for lifecycle improvement.   -# What Cyber Fabric is not: Positioning against existing tools +# What Constructor Fabric is not: Positioning against existing tools -### Module overview +## Module overview -This module clarifies what Cyber Fabric does and does not replace. +This module clarifies what Constructor Fabric does and does not replace. -Cyber Fabric should not be understood as a replacement for every tool in +Constructor Fabric should not be understood as a replacement for every tool in the software delivery stack. Teams may still use their existing IDEs, AI coding assistants, project management tools, Git repositories, CI/CD pipelines, service catalogs, cloud platforms, infrastructure systems, monitoring tools, and support systems. -The module explains that Cyber Fabric adds connection, governance, +The module explains that Constructor Fabric adds connection, governance, traceability, validation, reuse, and visibility around the existing toolchain. It is not an IDE, not a CI/CD tool, not a project tracker, not a service registry, and not production infrastructure. Its purpose is to connect and govern the lifecycle across these systems. -The key message is: Cyber Fabric complements the existing toolchain by +The key message is: Constructor Fabric complements the existing toolchain by connecting and governing delivery work rather than replacing every tool teams already use. Learning outcomes addressed -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Key repositories and when to use them +## Key repositories and when to use them -What Cyber Fabric does not replace +What Constructor Fabric does not replace -Cyber Fabric does not replace IDEs or AI coding tools. Developers may +Constructor Fabric does not replace IDEs or AI coding tools. Developers may still use Claude Code, Cursor, Copilot, Codex, or their preferred IDE. -Those tools help with coding. Cyber Fabric addresses the broader +Those tools help with coding. Constructor Fabric addresses the broader delivery system around coding: specifications, traceability, validation, governance, reuse, and measurement. -Cyber Fabric does not replace CI/CD tools such as Jenkins or GitHub +Constructor Fabric does not replace CI/CD tools such as Jenkins or GitHub Actions. It can work with those systems by adding structure, traceability, and validation rules that make pipeline checks more meaningful. -Cyber Fabric does not replace project management tools such as +Constructor Fabric does not replace project management tools such as Atlassian, Linear, or similar systems. It focuses on connecting the lifecycle artifacts behind the tasks: requirements, specifications, design, code, tests, deployments, and production feedback. -Cyber Fabric also does not replace service registries or cloud +Constructor Fabric also does not replace service registries or cloud infrastructure. Backstage and similar tools can remain. AWS, Azure, GCP, and other infrastructure choices can remain. -What Cyber Fabric adds instead +What Constructor Fabric adds instead -Cyber Fabric adds connection, governance, traceability, validation, +Constructor Fabric adds connection, governance, traceability, validation, reuse, and visibility around the existing toolchain. The point is not replacement. The point is to make the delivery lifecycle more connected and governed. @@ -1704,12 +1705,12 @@ Fabric can help link the requirement to a specification, connect the specification to code and tests, validate traceability in CI, and connect production feedback to future planning. -### Optional practical activity +## Optional practical activity **LO Alignment: **This activity addresses LO7 by asking learners to apply the replace, connect, and govern framing to a real toolchain. -Learners map Cyber Fabric against tools they already use and identify +Learners map Constructor Fabric against tools they already use and identify what stays in place. How to construct your answer @@ -1719,8 +1720,8 @@ AI coding assistant, CI/CD pipeline, project-management tool, cloud platform, monitoring system, or documentation tool. Then explain that this tool would stay in place. -Next, describe what Cyber Fabric would add around it. The key is not -replacement, but connection. For example, Cyber Fabric would not replace +Next, describe what Constructor Fabric would add around it. The key is not +replacement, but connection. For example, Constructor Fabric would not replace GitHub Actions, but it could help make the checks more meaningful by connecting them to requirements, validation rules, or traceability. It would not replace Jira, but it could help connect work items to design @@ -1728,39 +1729,39 @@ artifacts, code, tests, and operational feedback. A strong answer should clearly separate:\ - What stays in place: the existing tool;\ -- What Cyber Fabric adds: traceability, governance, validation, +- What Constructor Fabric adds: traceability, governance, validation, visibility, reuse, or delivery context;\ - Why this matters: one practical improvement for the delivery process.​ -The answer should show that Cyber Fabric complements the current +The answer should show that Constructor Fabric complements the current toolchain rather than replacing it. -### Module summary +## Module summary -This module clarified what Cyber Fabric does and does not replace. It -explained that Cyber Fabric should not be understood as a replacement +This module clarified what Constructor Fabric does and does not replace. It +explained that Constructor Fabric should not be understood as a replacement for every tool in the software delivery stack.\ \ The module showed that teams may continue using their existing IDEs, AI coding assistants, project management tools, Git repositories, CI/CD pipelines, service catalogs, cloud platforms, infrastructure systems, -monitoring tools, and support systems. Cyber Fabric adds value around +monitoring tools, and support systems. Constructor Fabric adds value around this existing toolchain by connecting and governing the delivery work that moves across those systems. It adds traceability, validation, visibility, reuse, and lifecycle connection around tools that may otherwise remain fragmented.\ \ -The lasting idea from this module is that Cyber Fabric is not a +The lasting idea from this module is that Constructor Fabric is not a rip-and-replace platform. Its value is in complementing the existing stack by connecting requirements, specifications, design, code, tests, deployment, production signals, and feedback into a more coherent and governed delivery flow.   -# Cyber Fabric compared with other AI and software development tools +# Constructor Fabric compared with other AI and software development tools -### Module overview +## Module overview -This module compares Cyber Fabric with other AI software development +This module compares Constructor Fabric with other AI software development tool categories. AI coding tools help individual developers write, explain, refactor, and @@ -1768,7 +1769,7 @@ review code faster. Spec-driven tools help teams move from structured requirements or specifications toward generated code. AI app builders help create simple applications, prototypes, and internal tools quickly. -Cyber Fabric addresses a broader lifecycle problem. It focuses on +Constructor Fabric addresses a broader lifecycle problem. It focuses on connecting requirements, design, code, tests, deployment, production, governance, reuse, measurement, and feedback. Its concern is not only whether code can be generated, but whether the work is traceable, @@ -1776,7 +1777,7 @@ validated, governed, deployable, observable, reusable, and connected to delivery outcomes. The key message is: AI coding tools accelerate individual coding tasks, -while Cyber Fabric supports lifecycle acceleration by connecting and +while Constructor Fabric supports lifecycle acceleration by connecting and governing the full delivery system. Learning outcomes addressed @@ -1784,13 +1785,13 @@ Learning outcomes addressed - LO2: Explain why faster code generation does not automatically mean faster software delivery; -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### How to compare tools responsibly +## How to compare tools responsibly Compared with AI coding tools @@ -1798,7 +1799,7 @@ AI coding tools make individual developers faster. They help generate code, explain code, refactor code, and create tests or suggestions. That is valuable, but it optimizes the coding step. -Cyber Fabric aims to make the organization faster by orchestrating the +Constructor Fabric aims to make the organization faster by orchestrating the lifecycle. It does not replace coding assistants. It governs and connects the work around them. @@ -1810,7 +1811,7 @@ Fabric adds traceability IDs, deterministic checks, compliance-aligned specification quality, brownfield support, cross-repository validation, and CI integration. -The key distinction is production-grade governance. Cyber Fabric is not +The key distinction is production-grade governance. Constructor Fabric is not only about creating specifications; it is about connecting specifications to design, code, tests, deployment, production behavior, and feedback. @@ -1818,15 +1819,15 @@ and feedback. Compared with AI app builders AI app builders can help non-developers create simple internal -applications or prototypes. Cyber Fabric is positioned for professional +applications or prototypes. Constructor Fabric is positioned for professional teams building enterprise-grade systems that require multi-tenancy, Kubernetes-native delivery, role-based access, attribute-based access, security requirements, automated tests, stress testing, load testing, CI, deployment, migrations, operations, and governance. -### Deeper dive: How to compare tools responsibly +## Deeper dive: How to compare tools responsibly -Cyber Fabric sits near several adjacent tool categories: AI coding +Constructor Fabric sits near several adjacent tool categories: AI coding assistants, spec-driven development tools, and AI app builders. The categories overlap, but they solve different parts of the delivery problem. A responsible comparison should therefore use evaluation @@ -1902,9 +1903,9 @@ connected delivery fabric becomes more important when work must be traceable, validated, reusable, measured, and governed across professional delivery environments. -### Module summary +## Module summary -This module compared Cyber Fabric with other AI software development +This module compared Constructor Fabric with other AI software development tool categories. It explained that AI coding tools, spec-driven tools, and AI app builders are useful, but they solve different parts of the delivery problem.\ @@ -1912,23 +1913,23 @@ delivery problem.\ The module showed that AI coding tools support individual coding tasks, spec-driven tools move from structured requirements toward generated outputs, and app builders support rapid creation of simple applications -or prototypes. Cyber Fabric addresses a broader lifecycle problem: +or prototypes. Constructor Fabric addresses a broader lifecycle problem: whether work is traceable, validated, governed, deployable, observable, reusable, measurable, and connected to delivery outcomes. Responsible comparison should consider lifecycle coverage, source of truth, traceability, deterministic validation, brownfield support, CI/CD fit, human approval, outcome measurement, and extensibility.\ \ -The lasting idea from this module is that Cyber Fabric belongs in the +The lasting idea from this module is that Constructor Fabric belongs in the lifecycle acceleration category. It complements generation tools by connecting requirements, design, code, tests, deployment, production, governance, measurement, and feedback.   # Unique capabilities for AI-Native software delivery -### Module overview +## Module overview -This module examines the specific capabilities that make Cyber Fabric +This module examines the specific capabilities that make Constructor Fabric useful for AI-native delivery. The module focuses on specification templates, checklists, customizable @@ -1956,13 +1957,13 @@ Learning outcomes addressed - LO3: Describe the plan-build-run model for AI-native software delivery; -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### How to evaluate AI-Native delivery capabilities in practice +## How to evaluate AI-Native delivery capabilities in practice By this point in the course, the main question is no longer only whether AI can help write code. The more important question is whether a @@ -2045,7 +2046,7 @@ When evaluating specification quality, ask:   - Could another developer understand the intended work without asking for a private explanation? -In Cyber Fabric terms, this is where structured delivery artifacts +In Constructor Fabric terms, this is where structured delivery artifacts matter. The value of an artifact is not that it creates documentation for its own sake. Its value is that it becomes shared context for planning, implementation, AI assistance, review, validation, and future @@ -2220,7 +2221,7 @@ delivery fabric by starting over. They need a way to connect what already exists. A useful system should help teams improve their current environment without demanding immediate rip-and-replace migration. -Cyber Fabric’s modular framing is relevant here. Constructor, Insight, +Constructor Fabric’s modular framing is relevant here. Constructor, Insight, and Ware can be understood as entry points rather than a single all-or-nothing replacement stack. A team might start with structured delivery artifacts, a metrics/Insight use case, or a reusable Ware-style @@ -2349,9 +2350,9 @@ and how to explain their change. That is why small contributions such as better acceptance criteria, clearer examples, improved checklists, or stronger documentation can be valuable. -### Module summary +## Module summary -This module examined the capabilities that make Cyber Fabric useful for +This module examined the capabilities that make Constructor Fabric useful for AI-Native delivery. It focused on durable specifications, checklists, governed code-generation workflows, traceability IDs, deterministic CI checks, requirements-quality alignment, cross-repository validation, @@ -2374,14 +2375,14 @@ remains aligned with intent.   # Adoption model: No lock-in, no rip-and-replace -### Module overview +## Module overview -This module explains how Cyber Fabric can be adopted incrementally. +This module explains how Constructor Fabric can be adopted incrementally. -Cyber Fabric is not designed as an all-or-nothing platform replacement. +Constructor Fabric is not designed as an all-or-nothing platform replacement. Teams do not need to abandon their existing IDEs, repositories, project trackers, CI/CD pipelines, cloud platforms, or monitoring systems. -Instead, they can start with the Cyber Fabric element that addresses +Instead, they can start with the Constructor Fabric element that addresses their clearest delivery problem. The module explains a problem-first adoption model. Teams may start with @@ -2390,23 +2391,23 @@ traceability and governance, or Cyber Ware for reusable components. It also introduces adoption levels that allow teams to move from feedback and visibility to governance and reusable component contribution. -The key message is: Cyber Fabric supports incremental adoption, allowing +The key message is: Constructor Fabric supports incremental adoption, allowing teams to keep their existing stack, start small, and expand based on practical value. Learning outcomes addressed -- LO5: Position Cyber Fabric as a practical implementation of AI-native +- LO5: Position Constructor Fabric as a practical implementation of AI-native software delivery; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Incremental integration with existing stacks +## Incremental integration with existing stacks Start with the delivery problem -Cyber Fabric adoption should begin with the delivery problem, not with +Constructor Fabric adoption should begin with the delivery problem, not with the assumption that the whole platform must be adopted at once. A team may have many tools already in place. It may already use an IDE, @@ -2433,7 +2434,7 @@ when the next element solves a real problem.   Use Cyber Insight, Cyber Constructor, or Cyber Ware independently -Cyber Fabric is modular by design. The three main elements can be used +Constructor Fabric is modular by design. The three main elements can be used independently and then combined as needed. **Cyber Insight is** relevant when the main problem is visibility. It @@ -2459,14 +2460,14 @@ when the next step has a clear purpose.   Keep the existing stack -Cyber Fabric is designed to work with existing tools, frameworks, and +Constructor Fabric is designed to work with existing tools, frameworks, and CI/CD. It does not require a platform replacement or architecture rewrite. It complements current engineering workflows. This matters because most teams already have a working software delivery environment. Replacing everything at once creates unnecessary disruption. A more practical approach is to keep the existing stack and -add Cyber Fabric capabilities where they solve a specific problem. +add Constructor Fabric capabilities where they solve a specific problem. For example, a team may already use: @@ -2481,7 +2482,7 @@ For example, a team may already use: | Monitoring | Existing observability or incident tools. | -Cyber Fabric does not need to replace these. The adoption question is +Constructor Fabric does not need to replace these. The adoption question is where connection, traceability, governance, reuse, or measurement should be added. A team that already has a CI/CD pipeline may add traceability checks or validation rules. A team that already has repositories may @@ -2491,7 +2492,7 @@ improvement. The key idea is not migration. The key idea is connection. Open, modular, and extensible -Cyber Fabric is also designed to be open, modular, and extensible. The +Constructor Fabric is also designed to be open, modular, and extensible. The foundation is open source under Apache 2.0, and the architecture is plugin-based and extensible. It supports most languages, stacks, and deployment models. @@ -2500,7 +2501,7 @@ This matters because different teams have different stacks. A delivery fabric cannot assume that every team uses the same language, framework, deployment model, or cloud environment. -Cyber Fabric’s adoption model supports that variation by allowing teams +Constructor Fabric’s adoption model supports that variation by allowing teams to start with one useful capability and extend from there. The open and plugin-based model also supports contribution. Teams can provide feedback, improve tools, improve components, develop new components, or @@ -2519,7 +2520,7 @@ The adoption model therefore has four connected ideas: Adoption levels -Cyber Fabric participation can also be understood through levels. +Constructor Fabric participation can also be understood through levels. | Level | Adoption focus | @@ -2555,7 +2556,7 @@ A good adoption path should answer three questions. | Question | Why it matters | |---|---| | What delivery problem is most visible now? | Adoption should begin with a real problem, not a general platform decision. | -| Which Cyber Fabric element addresses that problem most directly? | Cyber Insight, Cyber Constructor, and Cyber Ware solve different problems. | +| Which Constructor Fabric element addresses that problem most directly? | Cyber Insight, Cyber Constructor, and Cyber Ware solve different problems. | | What evidence will show whether the adoption helped? | Adoption should expand based on feedback and measurable value. | @@ -2567,7 +2568,7 @@ common services repeatedly should examine whether Cyber Ware components or contribution paths are the better starting point. The correct adoption path is the one that fits the problem. -### Optional practical activity +## Optional practical activity **LO Alignment: **This activity addresses LO7 by asking learners to recommend an incremental adoption move based on a specific delivery @@ -2575,10 +2576,10 @@ problem. **Design a Narrow Adoption Experiment** -Cyber Fabric is designed to support modular adoption. You do not need to +Constructor Fabric is designed to support modular adoption. You do not need to replace an existing development stack to begin evaluating its value. In this activity, you will apply the adoption model by designing one small -experiment that tests whether a Cyber Fabric capability could improve a +experiment that tests whether a Constructor Fabric capability could improve a specific delivery problem. The goal is not to design a full rollout. The goal is to define a @@ -2607,7 +2608,7 @@ problem, not a general desire to “improve development” or “use AI better.” The problem is specific enough to investigate: review speed is affected because reviewers do not have enough planning context. - 2. Cyber Fabric entry point: Which Cyber Fabric element is the best + 2. Constructor Fabric entry point: Which Constructor Fabric element is the best first entry point? Choose one: Constructor / Insight / Ware Constructor\ @@ -2625,7 +2626,7 @@ and implementation. A Constructor-oriented experiment can test whether clearer requirements, acceptance criteria, and delivery artifacts make implementation and review easier to understand.\ \ -This answer is appropriate because it connects the selected Cyber Fabric +This answer is appropriate because it connects the selected Constructor Fabric element directly to the delivery problem. It does not choose Constructor just because it is the most visible element; it chooses Constructor because the bottleneck is in the plan-to-build transition.​ @@ -2644,7 +2645,7 @@ structured delivery context around one feature.\ \ This is important because it respects the no-lock-in and no-rip-and-replace adoption model. The experiment is not a migration -project. It is a narrow test of whether one Cyber Fabric-style practice +project. It is a narrow test of whether one Constructor Fabric-style practice can improve one part of the existing delivery process.  5. Smallest thing to inspect or improve: What is the smallest artifact, @@ -2750,12 +2751,12 @@ the pilot across the organization. The answer shows that adoption should proceed through evidence: try, learn, refine, and expand only if the result is useful. -### Module summary +## Module summary -This module explained the Cyber Fabric adoption model. It clarified that -Cyber Fabric is not designed as an all-or-nothing platform replacement, +This module explained the Constructor Fabric adoption model. It clarified that +Constructor Fabric is not designed as an all-or-nothing platform replacement, and teams do not need to abandon their existing tools to begin using -Cyber Fabric concepts or capabilities.\ +Constructor Fabric concepts or capabilities.\ \ The module showed that adoption should begin with the clearest delivery problem. Teams lacking visibility may start with Cyber Insight. Teams @@ -2766,19 +2767,19 @@ then expand through levels, from visibility and feedback to governance and reusable component contribution, without treating the levels as a forced sequence.\ \ -The lasting idea from this module is that Cyber Fabric supports +The lasting idea from this module is that Constructor Fabric supports incremental adoption. Teams can keep their existing stack, start small, use the open and extensible model, solve a real delivery problem, and expand when there is evidence of value.   # How to participate: Use, fork, report issues, contribute -### Module overview +## Module overview This module prepares learners to complete the practical contribution requirement. -The course is not only about understanding Cyber Fabric conceptually. It +The course is not only about understanding Constructor Fabric conceptually. It also includes practical participation in the open-source ecosystem. Participation can be technical or non-technical. A valid contribution may include a GitHub issue, documentation improvement, clearer @@ -2789,9 +2790,9 @@ The module introduces three participation levels: Level 0, Level 1, and Level 2. Each level builds on the previous one, starting with Cyber Insight, then adding Cyber Constructor tools, and then adding Cyber Ware components. Additionally it introduces the six contribution paths -defined for Cyber Fabric. +defined for Constructor Fabric. -The key message is: Participation in Cyber Fabric can begin at different +The key message is: Participation in Constructor Fabric can begin at different levels, but valid course evidence must show a concrete GitHub contribution or structured participation activity. @@ -2800,11 +2801,11 @@ Learning outcomes addressed - LO4: Explain the role, mission, and open-source model of the Cyber Fabric Foundation. -### Contribution paths +## Contribution paths Choosing a contribution entry point -Cyber Fabric participation can connect to the same three levels +Constructor Fabric participation can connect to the same three levels introduced in the adoption model. A contribution may focus on Cyber Insight, Cyber Constructor tools, or Cyber Ware components. @@ -2825,7 +2826,7 @@ Cyber Constructor tools, then add Cyber Ware components. Contribution paths -Cyber Fabric defines six contribution paths. +Constructor Fabric defines six contribution paths. | No | Contribution path | Description | @@ -2833,12 +2834,12 @@ Cyber Fabric defines six contribution paths. | 1 | New skills, kits, and plugins for Cyber Constructor tools. | Provide new skills, kits, or plugins for Cyber Constructor tools. | | 2 | Improvements to Cyber Constructor tools. | Improve Cyber Constructor tools. | | 3 | Improvements to existing Cyber Ware components. | Improve existing Cyber Ware components. | -| 4 | New Cyber Ware components from the roadmap. | Develop new Cyber Ware components from the Cyber Fabric roadmap. | +| 4 | New Cyber Ware components from the roadmap. | Develop new Cyber Ware components from the Constructor Fabric roadmap. | | 5 | New Cyber Ware components outside the roadmap. | Propose and develop new Cyber Ware components not from the roadmap. | -| 6 | Third-party integrations. | Implement integrations between Cyber Fabric and third-party systems. | +| 6 | Third-party integrations. | Implement integrations between Constructor Fabric and third-party systems. | -These six paths define how participants can extend the Cyber Fabric +These six paths define how participants can extend the Constructor Fabric ecosystem.   Valid course evidence @@ -2876,48 +2877,48 @@ The evidence should show that participation has taken place. It should connect to one of the defined participation levels or contribution paths. -### Deeper dive: Choosing a useful cyber fabric contribution path +## Deeper dive: Choosing a useful constructor fabric contribution path The main module introduced the formal participation levels, the six contribution paths, and the kinds of evidence that count as course participation. This Deeper Dive helps you turn that framework into one -concrete action inside the Cyber Fabric GitHub ecosystem. +concrete action inside the Constructor Fabric GitHub ecosystem. You should not begin by asking, *What can I change?* Begin by -asking, *Which part of Cyber Fabric am I looking at, and what kind of +asking, *Which part of Constructor Fabric am I looking at, and what kind of contribution belongs there?* The answer depends on the repository, the evidence you find, and the contribution path that best fits the work. Start from the repository role -Cyber Fabric is a multi-repository ecosystem. You should use the +Constructor Fabric is a multi-repository ecosystem. You should use the repository map from Module 6 before choosing a contribution path. You -can also open the [Cyber Fabric GitHub -organization](https://github.com/cyberfabric) directly and inspect the +can also open the [Constructor Fabric GitHub +organization](https://github.com/constructorfabric) directly and inspect the repository list, but do not treat the repositories as a flat set of codebases. Each repository supports a different part of the delivery fabric. If you want to improve governed AI-assisted delivery, start with Constructor-oriented repositories such as [Cyber -Pilot](https://github.com/cyberfabric/cyber-pilot) or the [Cyber Pilot -SDLC kit](https://github.com/cyberfabric/cyber-pilot-kit-sdlc) These +Pilot](https://github.com/constructorfabric/cyber-pilot) or the [Cyber Pilot +SDLC kit](https://github.com/constructorfabric/cyber-pilot-kit-sdlc) These repositories are relevant when the issue is about requirements, artifacts, workflows, traceability, validation, or safe AI-assisted delivery examples. If you want to improve delivery measurement or analytics interpretation, -start with [Insight](https://github.com/cyberfabric/insight) or [Insight -Front](https://github.com/cyberfabric/insight-front). These repositories +start with [Insight](https://github.com/constructorfabric/insight) or [Insight +Front](https://github.com/constructorfabric/insight-front). These repositories are relevant when the issue is about metric definitions, connector scenarios, identity resolution, dashboard meaning, delivery bottlenecks, or AI adoption evidence. If you want to improve reusable platform, UI, documentation start with the relevant Ware-oriented repository. Useful starting points -include [CyberFabric -Core](https://github.com/cyberfabric/cyberfabric-core), [FrontX](https://github.com/cyberfabric/frontx), -and [DNA](https://github.com/cyberfabric/DNA). +include [ConstructorFabric +Core](https://github.com/constructorfabric/constructorfabric-core), [FrontX](https://github.com/constructorfabric/frontx), +and [DNA](https://github.com/constructorfabric/DNA). This repository selection step matters. A technically correct contribution can still be misplaced. An ambiguous Insight metric should @@ -2939,16 +2940,16 @@ the repository has Issues or Pull Requests enabled, inspect them to understand current problems and contribution patterns. A weak participation statement says: The docs should be better. A -stronger Cyber Fabric statement says: The SDLC kit explains artifact +stronger Constructor Fabric statement says: The SDLC kit explains artifact flow, but the validation point after modifying a kit artifact is not obvious. A short note after the setup instructions could help new users understand when to validate. The stronger statement names the repository area, the problem, the affected user, and a concrete improvement. Furthermore, the wording should reflect the products and the architecture -of the Github repositories because Cyber Fabric to make sure that -confusion is reduced. +of the GitHub repositories because Constructor Fabric helps make sure +that confusion is reduced. -Apply the six contribution paths to real Cyber Fabric work +Apply the six contribution paths to real Constructor Fabric work The main module lists six contribution paths. You should now connect those paths to the repository map. The purpose is not to choose the most @@ -2958,8 +2959,8 @@ repository, the evidence you found, and your current contribution depth. New skills, kits, and plugins for Cyber Constructor tools This path fits Constructor-oriented repositories, especially [Cyber -Pilot](https://github.com/cyberfabric/cyber-pilot) and the [Cyber Pilot -SDLC kit](https://github.com/cyberfabric/cyber-pilot-kit-sdlc). It is +Pilot](https://github.com/constructorfabric/cyber-pilot) and the [Cyber Pilot +SDLC kit](https://github.com/constructorfabric/cyber-pilot-kit-sdlc). It is relevant when you identify a repeatable workflow, artifact pattern, validation rule, or extension that could help Constructor tools support governed delivery more clearly. @@ -2974,8 +2975,8 @@ it would affect, and how it could be validated. Improvements to Cyber Constructor tools This is often the best first path for learners. It fits [Cyber -Pilot](https://github.com/cyberfabric/cyber-pilot), and the [Cyber Pilot -SDLC kit](https://github.com/cyberfabric/cyber-pilot-kit-sdlc). A useful +Pilot](https://github.com/constructorfabric/cyber-pilot), and the [Cyber Pilot +SDLC kit](https://github.com/constructorfabric/cyber-pilot-kit-sdlc). A useful improvement might clarify a workflow step, improve an artifact template, add acceptance criteria to a feature artifact, improve validation wording, or report ambiguity in artifact flow. @@ -2983,8 +2984,8 @@ wording, or report ambiguity in artifact flow. Improvements to existing Cyber Ware components This path fits existing reusable assets in repositories such -as [CyberFabric -Core](https://github.com/cyberfabric/cyberfabric-core), [FrontX](https://github.com/cyberfabric/frontx), [DNA](https://github.com/cyberfabric/DNA). +as [ConstructorFabric +Core](https://github.com/constructorfabric/constructorfabric-core), [FrontX](https://github.com/constructorfabric/frontx), [DNA](https://github.com/constructorfabric/DNA). You should consider it when an existing reusable component, tool, guideline, command, template, or documentation surface could be made clearer or easier to use. @@ -3069,7 +3070,7 @@ requirements, acceptance criteria, workflow instructions, setup guidance, validation notes, examples, templates, dashboards, metric definitions, documentation structure, and contribution explanations. -These contributions are valuable because Cyber Fabric is an AI-native +These contributions are valuable because Constructor Fabric is an AI-native delivery ecosystem. Humans and AI agents both need clearer context. A better acceptance criterion can make future AI-assisted implementation safer. A clearer validation note can make contribution review more @@ -3079,7 +3080,7 @@ model in a real workflow. This does not mean code contributions are unimportant. It means code contributions should come after the relevant repository, architecture, validation path, and maintainer expectations have been inspected. A deep -change to CyberFabric Core, Insight pipeline logic, FrontX internals, +change to ConstructorFabric Core, Insight pipeline logic, FrontX internals, code-generation behavior, or validation tooling should not be the first step unless you can explain the architecture and test path clearly. @@ -3087,7 +3088,7 @@ Make the contribution easy to review A useful contribution package should not be long, but it should answer the reviewer’s basic questions. What changed? Why does it matter in the -Cyber Fabric delivery model? Which repository surface is affected? What +Constructor Fabric delivery model? Which repository surface is affected? What evidence led to the change? How was it checked? What remains open? The summary should connect to delivery value. Updated docs is weak. For @@ -3102,10 +3103,10 @@ clarification, formatting cleanup, example change, and implementation patch in the same branch. A focused branch and clear pull request reduce review burden. -### Module summary +## Module summary -This module moved from learning about Cyber Fabric to participating in -the Cyber Fabric ecosystem. It explained that open-source participation +This module moved from learning about Constructor Fabric to participating in +the Constructor Fabric ecosystem. It explained that open-source participation is not limited to technical code contributions.\ \ The module showed that useful participation may take the form of a @@ -3125,12 +3126,12 @@ governance, reuse, integration, validation, or delivery practice.   # Role-based application paths -### Module overview +## Module overview -This module helps learners apply Cyber Fabric concepts to their own role +This module helps learners apply Constructor Fabric concepts to their own role or work context. -Cyber Fabric is relevant to different audiences in different ways. +Constructor Fabric is relevant to different audiences in different ways. Developers may focus on specifications, traceability, validation, repositories, and code-related contribution. Product staff may focus on requirements, acceptance criteria, roadmap alignment, and lifecycle @@ -3143,7 +3144,7 @@ integrations, reusable components, and customer use cases. The module helps learners move from understanding concepts to applying them in a practical context. -The key message is: Cyber Fabric concepts can be applied differently +The key message is: Constructor Fabric concepts can be applied differently across roles, but the shared goal is better connected, governed, and measurable delivery. @@ -3152,14 +3153,14 @@ Learning outcomes addressed - LO6: Explain the purpose of Cyber Constructor, Cyber Insight, and Cyber Ware; -- LO7: Apply Cyber Fabric concepts to their own role, work, or study +- LO7: Apply Constructor Fabric concepts to their own role, work, or study context. -### Role-based pathways +## Role-based pathways -Applying Cyber Fabric by role +Applying Constructor Fabric by role -Cyber Fabric is not only relevant to developers. It is a software +Constructor Fabric is not only relevant to developers. It is a software delivery model that affects how different roles define work, build work, validate work, measure work, reuse work, and improve work. @@ -3174,7 +3175,7 @@ is improving delivery outcomes. A partner or service provider may experience it as repeated customer-specific implementation work that could be handled through reusable components or integrations. -Cyber Fabric gives these roles a shared delivery language. The role +Constructor Fabric gives these roles a shared delivery language. The role focus may differ, but the same concepts remain important: traceability, validation, visibility, governance, reuse, measurement, and contribution. @@ -3183,20 +3184,20 @@ contribution. | Role context | Practical focus | |---|---| | Constructor Tech developers | Cyber Constructor, specifications, traceability, code validation, and contribution. | -| Acronis / Virtuozzo technical staff | Applying Cyber Fabric concepts to complex platform and SaaS delivery. | +| Acronis / Virtuozzo technical staff | Applying Constructor Fabric concepts to complex platform and SaaS delivery. | | Product / project / business staff | Plan-build-run, requirements, visibility, governance, and measurable improvement. | | Students | AI-native development concepts and open-source contribution practice. | | Acronis MSPs / Virtuozzo partners | Adoption levels, integration opportunities, Cyber Ware value, and customer use cases. | | Companies using Constructor Tech software | AI-assisted delivery, reusable software components, and governed adoption. | -> The key question for each role is not “Which Cyber Fabric term should I memorize?” The better question is: +> The key question for each role is not “Which Constructor Fabric term should I memorize?” The better question is: > -> *Which delivery problem does this role influence, and which Cyber Fabric concept helps address it?* +> *Which delivery problem does this role influence, and which Constructor Fabric concept helps address it?* Constructor Tech developers: traceability, validation, and contribution -For developers, Cyber Fabric concepts are closely connected to +For developers, Constructor Fabric concepts are closely connected to specifications, traceability, validation, repositories, and contribution. @@ -3213,7 +3214,7 @@ deployments, and operations into a connected flow. It also supports traceability IDs, deterministic CI checks, cross-repository validation, and AI governance. -A developer applying Cyber Fabric concepts might ask: +A developer applying Constructor Fabric concepts might ask: | Developer question | Why it matters | @@ -3234,7 +3235,7 @@ Acronis and Virtuozzo technical staff: complex platform and SaaS delivery Technical staff working in complex platform, infrastructure, or SaaS -environments may apply Cyber Fabric concepts at a broader system level. +environments may apply Constructor Fabric concepts at a broader system level. These environments often involve multiple services, repositories, deployment targets, infrastructure layers, APIs, security controls, and @@ -3254,7 +3255,7 @@ integration engines. A technical platform application might look like this: -| Delivery concern | Cyber Fabric application | +| Delivery concern | Constructor Fabric application | |---|---| | Multiple repositories must stay consistent. | Use traceability and cross-repository validation. | | AI-generated code must follow architecture rules. | Use specifications, checklists, and validation checks. | @@ -3269,7 +3270,7 @@ contribution, or structured feedback on toolchain fit. Product staff: requirements and acceptance criteria -For product staff, Cyber Fabric concepts are most closely connected to +For product staff, Constructor Fabric concepts are most closely connected to requirement quality, acceptance criteria, roadmap clarity, and lifecycle visibility. @@ -3310,7 +3311,7 @@ requirement or workflow. Project and delivery staff: bottlenecks, dependencies, and coordination -For project and delivery staff, Cyber Fabric concepts are most closely +For project and delivery staff, Constructor Fabric concepts are most closely connected to workflow visibility, bottleneck detection, dependencies, and delivery coordination. @@ -3324,7 +3325,7 @@ benchmarking, roles, activities, source-system connectors, AI adoption correlation, and visibility across teams and tools. It helps move delivery conversations away from guesswork and toward evidence. -A project or delivery role might use Cyber Fabric concepts to ask: +A project or delivery role might use Constructor Fabric concepts to ask: | Delivery question | Possible signal | @@ -3343,7 +3344,7 @@ build, and run are weak. Business staff: adoption value, risk, and measurable improvement -For business staff, Cyber Fabric concepts are most closely connected to +For business staff, Constructor Fabric concepts are most closely connected to adoption value, operational risk, productivity visibility, and measurable improvement. @@ -3376,7 +3377,7 @@ Cyber Ware should be piloted first. Students and new contributors: learning through practical participation -For students and new contributors, Cyber Fabric provides a way to learn +For students and new contributors, Constructor Fabric provides a way to learn modern AI-native delivery through real open-source participation. Contribution does not need to begin with code. A student may review @@ -3419,7 +3420,7 @@ delivery, open-source collaboration, and practical improvement. Partners and service providers: integrations, reusable components, and customer use cases -For partners and service providers, Cyber Fabric concepts are closely +For partners and service providers, Constructor Fabric concepts are closely connected to adoption levels, integration opportunities, Cyber Ware value, and customer use cases. @@ -3429,7 +3430,7 @@ difficult to maintain. Cyber Ware is relevant because it focuses on reusable components, business support modules, operational support modules, platform services, and integration engines. -Partners may also identify useful integrations between Cyber Fabric and +Partners may also identify useful integrations between Constructor Fabric and third-party systems. These could include service desks, monitoring tools, CRM systems, billing platforms, identity providers, CI/CD systems, or cloud platforms. @@ -3437,7 +3438,7 @@ systems, or cloud platforms. A partner or service provider might ask: -| Partner question | Cyber Fabric connection | +| Partner question | Constructor Fabric connection | |---|---| | Which customer problems repeat across environments? | Cyber Ware component opportunity | | Which third-party systems need to connect? | Integration proposal | @@ -3452,7 +3453,7 @@ GitHub issue describing a repeatable customer need. Companies using Constructor Tech software: governed AI-assisted delivery -Companies using Constructor Tech software may apply Cyber Fabric +Companies using Constructor Tech software may apply Constructor Fabric concepts to improve AI-assisted delivery without replacing their existing tools or workflows. @@ -3464,7 +3465,7 @@ Fabric concepts help connect the work across those systems. A company might begin by asking: -| Current challenge | Cyber Fabric concept | +| Current challenge | Constructor Fabric concept | |---|---| | AI-generated code is hard to validate. | Cyber Constructor, traceability, validation. | | Delivery bottlenecks are unclear. | Cyber Insight, productivity benchmarking. | @@ -3479,7 +3480,7 @@ traceability, or repeated component development. Then they can decide whether Cyber Insight, Cyber Constructor, or Cyber Ware is the most appropriate first step. -Connecting role needs to Cyber Fabric elements +Connecting role needs to Constructor Fabric elements Cyber Constructor, Cyber Insight, and Cyber Ware support different needs, but they are not limited to one audience. @@ -3503,13 +3504,13 @@ for validation and Cyber Ware for reusable patterns. A partner may use Cyber Ware for reusable components and Cyber Insight to identify adoption value. -The important decision is not which role “owns” Cyber Fabric. The +The important decision is not which role “owns” Constructor Fabric. The important decision is which delivery problem needs to be improved and -which Cyber Fabric element can help. +which Constructor Fabric element can help. -### Module summary +## Module summary -This module showed how Cyber Fabric concepts apply across different +This module showed how Constructor Fabric concepts apply across different roles and work contexts. It explained that AI-native delivery is not owned by one role, because different people influence different parts of the same delivery lifecycle.\ @@ -3525,7 +3526,7 @@ service providers, and companies using Constructor Tech software may propose integrations, reusable components, customer use cases, or ecosystem improvements.\ \ -The lasting idea from this module is that Cyber Fabric becomes useful +The lasting idea from this module is that Constructor Fabric becomes useful when each role strengthens the part of delivery it influences and connects that work to intent, implementation, validation, operations, measurement, reuse, contribution, and feedback.   @@ -3533,7 +3534,7 @@ measurement, reuse, contribution, and feedback.   # Final exam Welcome to the graded assessment for this module. This quiz is designed -to evaluate your understanding of the **Cyber Fabric** ecosystem. Please +to evaluate your understanding of the **Constructor Fabric** ecosystem. Please review the following instructions carefully before beginning your attempt. diff --git a/courses/mapped-studio-content.md b/courses/mapped-studio-content.md new file mode 100644 index 0000000..fee1adc --- /dev/null +++ b/courses/mapped-studio-content.md @@ -0,0 +1,3268 @@ +# Constructor Studio Academy: Build a Todo App With AI Agents + +> Version boundary: Constructor Studio v1.0.0 only. +> +> This course content is validated against Constructor Studio v1.0.0 source documentation only. Any other product version, fork, or host-integration revision requires a fresh source review before reuse. + +## What You Will Build + +In this course you will use Constructor Studio to build and review a small Todo app. The core path uses one canonical architecture: a TypeScript HTTP API backend plus a React client. By the end, you will have a review-ready project package with: + +- the SDLC (Software Development Lifecycle) kit installed and validated; +- a short Todo intent refined through `cf-brainstorm` into an input brief; +- SDLC artifacts (`PRD`, `ADR`, `DESIGN`, `DECOMPOSITION`, and `FEATURE`); +- checkpoint evidence in `docs/course-notes.md`; +- a TypeScript HTTP API backend slice; +- a React UI slice connected to that backend; +- code traceability markers linking implementation to FEATURE IDs when the kit enables traceability; +- validation output; +- behavior proof for list, create, toggle, and delete; +- review findings and fixes; +- a final handoff package explaining what changed, what evidence exists, and what still needs human approval. + +This course is operator-first. You are learning the day-one workflow for using Constructor Studio on a Todo project safely and repeatably. It assumes basic repo, Git, and terminal familiarity. Custom authoring, extension work, and deeper host tailoring come later, after you can operate the standard workflows with confidence. + +The app stays intentionally small. The point is not to teach React or backend design from scratch. The point is to teach you how to use Constructor Studio so AI-assisted work remains bounded, traceable, reviewable, and safe. + +Optional variant: + +- an in-process service or adapter layer may exist behind the HTTP API if the repo already uses that pattern; +- do not make that the primary course architecture; +- do not switch from HTTP API to in-process-only behavior on the core path without an explicit repo-specific reason. + +The course works with Claude Code, Codex, or both. The core artifact-authoring path requires whichever host you use to preserve Constructor Studio routing, read-only analysis, and write gates. Use the host you prefer after it passes the Module 3 host gate; if a host surface is stale or misconfigured, regenerate its integration, reopen or reload it, and rerun the gate before continuing. + +## How To Take This Course + +Use one repo throughout the course. The repo may be empty at first, or it may already contain a small Todo app. Your evidence file for this course is `docs/course-notes.md`. If `docs/` does not exist yet, create it first. Put every checkpoint, command log, validation note, and review evidence in that file. + +When you see a terminal command, run it in your shell from the repo root. When you see a chat prompt, paste it into Claude Code or Codex after Constructor Studio is active. + +Canonical forms: + +- Terminal commands use `cfs`. +- Prompt cards are copy-paste ready. When a course step has a chat prompt, it should show a Claude Code block and a Codex block. +- The workflow intent is usually identical in both hosts, but the copy-paste command prefix is not. +- Claude Code prompt cards start with `/cf` (activation) or a specific skill name, for example `/cf-coding`, `/cf-write-docs`, `/cf-sdlc-doc-prd`, or `/cf-sdlc-implement`. +- Codex prompt cards use the same names with the dollar prefix: `$cf`, `$cf-coding`, `$cf-write-docs`, `$cf-sdlc-doc-prd`, `$cf-sdlc-implement`. +- Pick the specialized command for the job. The SDLC kit skills (`cf-sdlc-doc-prd`, `cf-sdlc-doc-adr`, `cf-sdlc-doc-design`, `cf-sdlc-decompose`, `cf-sdlc-doc-feature`, `cf-sdlc-implement`) author and review their own artifact, and core skills like `cf-coding` and `cf-write-docs` both write and review through a built-in review-fix loop. +- For activation, Claude Code uses `/cf`; Codex uses `$cf`. The task text follows the command name (no colon needed), for example `/cf-auto-config` in Claude Code or `$cf-auto-config` in Codex. +- Codex defaults to an autonomous mode that runs ahead and skips the interactive gates Constructor Studio relies on. Start every Codex session with `disable autonomous mode` (best practice; or set it as a system prompt) so sub-agent approval, git-commit mode, brainstorm offers, and per-write confirmations actually appear. See Lesson 2.3. Claude Code respects the gates by default. +- SDLC and Cypilot migration skills appear in the skill list but are reference-only in this course. + +Starter `docs/course-notes.md` template: + +```markdown +# Course Notes + +## Setup Evidence +| Item | Value | +|---|---| +| Course repo root | | +| Setup state | | +| Current next step | | + +## Command Log +| Command | Purpose | Result | Log excerpt or path | +|---|---|---|---| +| | | | | + +## Validation Log +| Command | Scope | Pass/Fail/N/A | Output excerpt or log path | +|---|---|---|---| +| | | | | + +## Review Cycle Log +| Cycle | Prompt or review source | Findings in scope | Decision | Follow-up | +|---|---|---|---|---| +| | | | | | + +## Plan-State Snapshots +| Moment | Plan path | plan.execution_status | plan.lifecycle_status | phases[].status | +|---|---|---|---|---| +| | | | | | + +## SDLC Artifact Chain +| Layer | Artifact path | Key IDs | Validation result | +|---|---|---|---| +| PRD | | | | +| ADR | | | | +| DESIGN | | | | +| DECOMPOSITION | | | | +| FEATURE | | | | +| CODEBASE implementation + traceability | | | | + +## Conflict Table +| Course guidance | Observed/source truth | Impact | Decision | +|---|---|---|---| +| | | | | + +## Brownfield/Workspace Evidence +| Topic | Evidence | Impact on this repo | +|---|---|---| +| | | | +``` + +## Module 1. Orientation: What Constructor Studio Adds + +### Lesson 1.1. The Four Actors + +Constructor Studio is a repo-attached workflow, context, and validation layer around an AI coding tool. It does not replace judgment. + +There are four actors: + +- Human: approves scope and accepts the final result. +- Host: Claude Code or Codex, the environment where the agent runs. +- Agent: the reasoning and writing executor inside the host. +- Constructor Studio: the workflow, context, routing, and validation layer. + +Your operating rule for the rest of the course: + +```text +approved SDLC artifact chain -> bounded plan -> implementation with traceability -> deterministic checks -> semantic review -> human approval +``` + +If a step skips that chain, stop and recover before continuing. + +Do this as a thinking check, not a file-writing exercise yet: + +1. Name the four actors in your own words. +2. Say what each actor is allowed to decide. +3. Say this sentence out loud or write it in temporary notes: `A passing validator is not human approval.` + +Checkpoint: + +- You can distinguish the human, host, agent, and Constructor Studio roles. +- You understand that validation evidence supports review; it does not replace approval. + +### Lesson 1.2. The Running Todo Project + +You will build a Todo app through small, reviewable steps. The app will eventually support four core behaviors: + +- list todos; +- create a todo with a title; +- mark a todo complete or incomplete; +- delete a todo. + +Do not write the Todo intent or input brief yet. First you need a real course folder, a working `cfs` install, Constructor Studio initialized in that folder, the SDLC kit installed, and host integrations generated. Prompts start only after setup is complete. + +Checkpoint: + +- You understand the target app shape. +- You did not invent a learner repo URL or rely on a hidden sample repo. + +## Module 2. Setup For Claude Code And Codex + +### Lesson 2.1. Create The Course Folder And Install `cfs` + +Start from a clean course folder. The course assumes you initialize Constructor Studio yourself; it does not assume a preconfigured repo. + +Terminal preflight: + +```bash +mkdir -p todo-course +cd todo-course +pwd +git status --short +python3 --version +pipx --version +``` + +If `git status --short` fails because this is not a Git repo yet, initialize one before continuing: + +```bash +git init +``` + +If `python3` is older than 3.11, fix Python first. If `pipx` is missing, install or repair it before continuing. + +Checkpoint: + +- You are in the course repo root. +- `git status --short` works. +- You have not opened Claude Code or Codex for course prompts yet. + +Verify your prerequisites before continuing: + +```bash +python3 --version +pipx --version +``` + +If `pipx` is missing, use the smallest platform-appropriate recovery: + +macOS: + +```bash +brew install pipx +pipx ensurepath +``` + +Linux: + +```bash +python3 -m pip install --user pipx +python3 -m pipx ensurepath +``` + +Windows PowerShell: + +```powershell +py -m pip install --user pipx +py -m pipx ensurepath +``` + +The core course command path assumes a POSIX-compatible shell: macOS Terminal, Linux, WSL, or Git Bash on Windows. If you choose native PowerShell after installation, translate POSIX commands explicitly and record the PowerShell equivalent in `docs/course-notes.md` before continuing. + +Then open a new terminal. On macOS `zsh`, or if you intentionally want to reload the current shell: + +```bash +source ~/.zshrc +``` + +Install the Constructor Studio CLI at the course version boundary, then verify it: + +```bash +pipx install "git+https://github.com/constructorfabric/studio.git@v1.0.0" +cfs --version +``` + +Expected `cfs --version` semantics: + +- the output must report version `1.0.0` for this course line; +- patch or host packaging details may vary, but the reported Studio version must still resolve to `1.0.0`; +- if `cfs --version` reports another major or minor version, stop and reconcile before continuing. + +If `cfs` is still missing after install, recover in this order: + +1. Open a new terminal. +2. On macOS `zsh`, run `source ~/.zshrc`. +3. Re-check `pipx --version`. +4. Re-check `cfs --version`. + +Once `cfs --version` works, initialize the repo: + +```bash +cfs init +``` + +During `cfs init`, use the defaults unless you intentionally need a custom project root or Constructor Studio directory. When the SDLC kit prompt appears, choose `a` to install it. When kit resource paths are shown, press Enter for each default path. + +You do not need to read every generated resource path. The important choices are: + +```text +Project root directory? [current repo] -> press Enter +Constructor Studio directory? [.cf-studio] -> press Enter +Install SDLC kit (constructorfabric/studio-kit-sdlc)? -> type a +Kit root directory [...] -> press Enter +Resource '...' path [...] -> press Enter for each resource +``` + +A successful init ends with a summary like this: + +```text +Constructor Studio Init + Project: TodoCourse + Constructor dir: .cf-studio/ + +Core files copied to .core/ +Config created in config/ +Kits installed: + sdlc: files generated +AGENTS.md navigation block injected into project root + +Constructor Studio initialized! + +Next steps: + 1. Set up your IDE: cfs generate-agents + 2. Review config: open .cf-studio/config/core.toml + 3. Start using: type '/cf' in your IDE chat +``` + +If your `cfs init` flow does not offer the kit, or if you accidentally decline it, install the kit explicitly before continuing: + +```bash +cfs kit install constructorfabric/studio-kit-sdlc +cfs info +cfs validate-kits --kit sdlc +``` + +`cfs validate-kits .` is a useful general kit-template validation command, but for this course the SDLC proof must include `cfs info` plus `cfs validate-kits --kit sdlc`, so you know the installed `sdlc` kit is the one being checked. + +After init, `cfs info` should show the project, the `.cf-studio` adapter directory, and the SDLC kit registration. A shortened healthy shape looks like this: + +```text +Constructor Studio Project Info + Project root: .../todo-course + Adapter dir: .cf-studio + Config version: 1.0 + +Kits (1) + sdlc v1.0.0 + Content: artifacts, codebase, scripts, workflows + Artifact kinds: ADR, DECOMPOSITION, DESIGN, FEATURE, PRD, ... + Workflows: migrate-openspec, pr-review, pr-status + +Systems (1) + TodoCourse (...) kit=sdlc +``` + +The full output may list many resources and variables. You do not need to copy them all into `docs/course-notes.md`; record the evidence that `sdlc v1.0.0` is present, the system is `TodoCourse`, and the kit content includes artifacts and workflows. + +Do not continue to Module 3 without the SDLC kit. Without it, the course cannot teach the required PRD -> ADR + DESIGN -> DECOMPOSITION -> FEATURE -> CODE flow. + +Generate host integrations for the host you will use. + +Claude Code: + +```bash +cfs generate-agents --agent claude +``` + +Expected Claude preview shape: + +```text +Generate Agent Integration — claude + + claude: + + .claude/skills/cf/SKILL.md (created) + + .claude/skills/cf-generate/SKILL.md (created) + + .claude/skills/cf-analyze/SKILL.md (created) + + .claude/skills/cf-plan/SKILL.md (created) + + .claude/agents/cf-phase-runner.md (created) + + .claude/agents/cf-semantic-reviewer-artifact.md (created) + + ... many more generated skills and agents ... + +Reply with `y` to write these generated files or `n` to abort. +Proceed? [Y/n] +``` + +The long list is normal. It is a preview of generated Claude skills and agents. If the target is your course repo and the create/update set matches `claude`, answer `y`. + +After you confirm, a successful run ends with a summary like this: + +```text +27 skill file(s), 42 subagent file(s) + +Agent integration complete! + +Your IDE will now: + - Route /cf-generate, /cf-analyze, /cf-plan, and /cf-workspace to Constructor Studio workflows + - Recognize the Constructor Studio skill in chat +``` + +The exact counts may change with the installed Studio version, but for this v1.0.0 course the important signal is `Agent integration complete!`. + +Codex: + +```bash +cfs generate-agents --agent openai +``` + +Expected OpenAI/Codex preview shape: + +```text +Generate Agent Integration — openai + + openai: + + .agents/skills/cf/SKILL.md (created) + + .agents/skills/cf-generate/SKILL.md (created) + + .agents/skills/cf-analyze/SKILL.md (created) + + .agents/skills/cf-plan/SKILL.md (created) + + .codex/agents/cf-phase-runner.toml (created) + + .codex/agents/cf-semantic-reviewer-artifact.toml (created) + + ... many more generated skills and agents ... + +Reply with `y` to write these generated files or `n` to abort. +Proceed? [Y/n] +``` + +The long list is normal here too. For Codex, skills are generated under `.agents/skills/`, and subagents are generated as `.codex/agents/*.toml`. If the target is your course repo and the create/update set matches `openai`, answer `y`. + +After you confirm, a successful OpenAI/Codex run also ends with a summary like this: + +```text +27 skill file(s), 42 subagent file(s) + +Agent integration complete! + +Your IDE will now: + - Route /cf-generate, /cf-analyze, /cf-plan, and /cf-workspace to Constructor Studio workflows + - Recognize the Constructor Studio skill in chat +``` + +The exact counts may change with the installed Studio version, but the important signal is still `Agent integration complete!`. + +`cfs generate-agents` may preview files or pause for confirmation before writing. Answer the prompt, let generation finish, then reopen or reload the host so it picks up the generated files. Rerunning `cfs generate-agents` fully regenerates generated host entry points; do not hand-edit generated host files. Keep project-specific changes in the actual source-of-truth files instead. + +Both hosts: + +```bash +cfs generate-agents --agent claude +cfs generate-agents --agent openai +``` + +After generating agents, rerun: + +```bash +cfs info +``` + +The `Agent integrations` section should include the host or hosts you generated: + +```text +Agent integrations + claude + openai +``` + +If you generated only one host, seeing only that host is fine. If you generated both Claude and OpenAI/Codex, both should appear. + +Expected result: + +- `.cf-studio/` exists. +- The SDLC kit is installed or explicitly installed immediately after init. +- `cfs info` shows the `sdlc` kit is registered, and `cfs validate-kits --kit sdlc` passes. Any kit installation problem is recorded as a blocker. +- Claude Code setups typically include generated `.claude/skills/` and `.claude/agents/`. +- Codex setups typically include shared `.agents/skills/`, a `.codex/` installation marker, and `.codex/agents/` with a TOML agent file. +- Generated host files are integration surfaces, not source-of-truth files. Keep requests explicit and bounded in both hosts. +- No setup command was run from the wrong repo. + +Troubleshooting: + +- If `pipx` is not found, install `pipx`, update `PATH`, open a new terminal, and rerun `pipx --version`. +- If `cfs` is not found after install, open a new terminal, run `source ~/.zshrc` on macOS `zsh`, then rerun `pipx --version` and `cfs --version`. +- If `cfs generate-agents` looks stalled, it may be waiting for confirmation before writing files. +- If generated files are not picked up, reopen or reload the host after generation completes. +- If you think setup ran in the wrong place, re-check in order: `pwd`, `git status --short`, `pipx --version`, `cfs --version`. + +Now create the course evidence file: + +```bash +mkdir -p docs +touch docs/course-notes.md +``` + +Add these headings to `docs/course-notes.md`: + +```markdown +# Course Notes + +## Setup Evidence + +## Activation Evidence + +## Brainstorm And Intent + +## SDLC Artifact Chain + +## Validation Log + +## Review Cycle Log +``` + +Add the sentence `A passing validator is not human approval.` under `Setup Evidence`. + +Checkpoint: + +- `docs/course-notes.md` records the exact setup commands you ran. +- `docs/course-notes.md` records that you accepted or installed the SDLC kit and includes the `cfs info` registration evidence plus the `cfs validate-kits --kit sdlc` result. +- `docs/course-notes.md` names the generated host surfaces that match your chosen host. + +### Lesson 2.2. Make The Initial Commit + +Create the initial Git commit before any brainstorm or sub-agent workflow. This module is design-first, so there is nothing to build by hand. The application itself is created later, when the agent implements the FEATURE in Module 4. + +Native sub-agent dispatch needs a valid Git `HEAD`: a freshly initialized repo with no commits can pass `git status`, but still fail sub-agent dispatch because `git rev-parse HEAD` has nothing to resolve. This commit captures the initialized Studio workspace only. + +Check for `HEAD`: + +```bash +git rev-parse --verify HEAD +``` + +If that command fails, create the initial course setup commit: + +```bash +git status --short +git add . +git commit -m "chore: initialize Constructor Studio todo course" +git rev-parse --short HEAD +``` + +Expected result: + +- The first commit may be large. Seeing many files is normal because `.cf-studio/`, SDLC kit resources, and the generated Claude/Codex host integrations are all part of the initialized course workspace. +- The important success signal is that `git rev-parse --short HEAD` prints a short commit hash such as `b4a1e9e`. +- Record that hash in `docs/course-notes.md` under setup evidence. + +If `git commit` fails because Git identity is not configured, configure your Git identity using your normal project policy, then rerun the commit. Do not continue to Module 3 until `git rev-parse --verify HEAD` succeeds. + +### Lesson 2.3. Activate Constructor Studio In Chat + +1. Open Claude Code or Codex in the repo root. + +2. Before activating Constructor Studio, set the working model profile. + +Claude Code: + +```text +/model Sonnet +/effort medium +``` + +Prefer regular Sonnet without a `[1m]` suffix for this course. In Claude Code, type `/model Sonnet` directly; opening `/model` without an argument may show a picker that keeps or selects `Sonnet (1M context)`. If you accidentally land on 1M context, type `/model Sonnet` again, then verify the status line says `Sonnet with medium effort` rather than `Sonnet (1M context)`. If Claude Code still will not let you remove 1M context, do not block the course. Keep Sonnet with medium effort. Record `Claude context: 1M could not be disabled` in `docs/course-notes.md`, then continue. + +Codex: + +```text +Model: gpt-5.4 +Reasoning: medium +``` + +Use the Codex model picker, session settings, or config surface available in your install before running `$cf`. The goal is GPT-5.4 with medium reasoning for the course path. + +Codex also defaults to an autonomous mode that can run ahead and skip the interactive gates Constructor Studio relies on — sub-agent approval, git-commit mode, brainstorm offers, and per-write confirmations. Turn it off once at the start of every Codex session, before `$cf`: + +```text +disable autonomous mode +``` + +Keep this as your first Codex message each session, or set it as a system or config instruction so it always applies — disabling autonomy at session start is the best practice. With autonomy off, the gates appear exactly as this course describes and you approve every write. + +If you cannot disable autonomous mode, use the two-prompt fallback for each skill: send the bare load command first (for example `$cf-sdlc-doc-prd`), let the skill load and present its gates, then send the intent as a separate follow-up message. Claude Code does not need this; it respects the gates by default. + +3. Activate Constructor Studio. + +Claude Code: + +```text +/cf +``` + +Codex: + +```text +$cf +``` + +Expected result after activation: + +- You get a clear activation confirmation or workflow-aware acknowledgement. +- The host behaves like Constructor Studio is active for this repo, not like a generic assistant with no repo-aware workflow layer. + +Claude Code activation commonly looks like this when you type only `/cf` without naming a workflow. Constructor Studio first loads its core rules and reports them, then asks you to pick a workflow skill: + +```text +Constructor Studio loaded (cf). Rule sources loaded: .cf-studio/.gen/AGENTS.md, +.cf-studio/.gen/SKILL.md, .cf-studio/config/ (when present), the core PDSL +execution card, and the cf SKILL units. cf is ready. + +No task intent in the prompt. Showing all available cf-* skills. + +Pick a cf-* skill by number to run it. + +Core workflows: +1. cf-analyze — analyze artifacts, code, or the codebase +2. cf-auto-config — auto-configure the studio +3. cf-brainstorm — run a brainstorm panel +4. cf-coding — write, implement, or fix code +5. cf-debug-prompts — debug prompt / skill issues +6. cf-explain — explain, walk through, or narrate a topic or artifact +7. cf-explore — explore, discover, or survey the project +8. cf-generate — create, update, or regenerate artifacts +9. cf-help — get help with Constructor Studio +10. cf-map — build an interactive dependency map +11. cf-plan — plan work before executing it +12. cf-studio — session management (alias of cf) +13. cf-workspace — set up or manage a multi-repo workspace +14. cf-write-docs — write or revise documentation +15. cf-write-skills — write or revise skills + +Kit: sdlc workflows: +16. cf-sdlc-change-impact-analysis — analyze change impact across artifacts +17. cf-sdlc-decompose — decompose a PRD/DESIGN into a DECOMPOSITION artifact +18. cf-sdlc-doc-adr — author or revise an ADR +19. cf-sdlc-doc-design — author or revise a DESIGN artifact +20. cf-sdlc-doc-feature — author or revise a FEATURE artifact +21. cf-sdlc-doc-prd — author or revise a PRD +22. cf-sdlc-implement — implement a FEATURE as code +23. cf-sdlc-migrate-openspec — migrate OpenSpec artifacts into the SDLC pipeline +24. cf-sdlc-pr-review — review a pull request +25. cf-sdlc-pr-status — get the status of a PR +26. cf-sdlc-reverse-engineer — reverse-engineer existing code into SDLC artifacts + +27. none — stop +``` + +This is a valid activation signal. It means Constructor Studio loaded its core rules and is offering the available `cf-*` workflow skills. The agent shows the same load report and skill menu in both hosts; only the prefix you typed differs (`/cf` in Claude Code, `$cf` in Codex). Because you typed `/cf` with no task intent, the menu lists every available skill and pre-selects none; when your prompt does carry an intent, the matching skill is tagged `(suggested)`. After activation a write gate is held: the agent can inspect and route, but it cannot write files until a workflow releases the gate and you confirm each write. SDLC and Cypilot migration skills appear in the list but are reference-only in this course. For this lesson, do not pick a write-capable skill yet; continue with the read-only `cf-explore` check in Lesson 2.4. + +Codex activation commonly looks like this (same load report and skill menu; you type `$cf` instead of `/cf`): + +```text +Constructor Studio loaded (cf). Rule sources loaded: .cf-studio/.gen/AGENTS.md, +.cf-studio/.gen/SKILL.md, .cf-studio/config/ (when present), the core PDSL +execution card, and the cf SKILL units. cf is ready. + +No task intent in the prompt. Showing all available cf-* skills. + +Pick a cf-* skill by number to run it. + +Core workflows: +1. cf-analyze — analyze artifacts, code, or the codebase +2. cf-auto-config — auto-configure the studio +3. cf-brainstorm — run a brainstorm panel +4. cf-coding — write, implement, or fix code +5. cf-debug-prompts — debug prompt / skill issues +6. cf-explain — explain, walk through, or narrate a topic or artifact +7. cf-explore — explore, discover, or survey the project +8. cf-generate — create, update, or regenerate artifacts +9. cf-help — get help with Constructor Studio +10. cf-map — build an interactive dependency map +11. cf-plan — plan work before executing it +12. cf-studio — session management (alias of cf) +13. cf-workspace — set up or manage a multi-repo workspace +14. cf-write-docs — write or revise documentation +15. cf-write-skills — write or revise skills + +Kit: sdlc workflows: +16. cf-sdlc-change-impact-analysis — analyze change impact across artifacts +17. cf-sdlc-decompose — decompose a PRD/DESIGN into a DECOMPOSITION artifact +18. cf-sdlc-doc-adr — author or revise an ADR +19. cf-sdlc-doc-design — author or revise a DESIGN artifact +20. cf-sdlc-doc-feature — author or revise a FEATURE artifact +21. cf-sdlc-doc-prd — author or revise a PRD +22. cf-sdlc-implement — implement a FEATURE as code +23. cf-sdlc-migrate-openspec — migrate OpenSpec artifacts into the SDLC pipeline +24. cf-sdlc-pr-review — review a pull request +25. cf-sdlc-pr-status — get the status of a PR +26. cf-sdlc-reverse-engineer — reverse-engineer existing code into SDLC artifacts + +27. none — stop +``` + +4. Confirm read-only routing before any setup prompt that can write. + +Claude Code prompt: + +```text +/cf-explore summarize the current repo structure and identify the safest next setup step. Do not modify files. +``` + +Codex prompt: + +```text +$cf-explore summarize the current repo structure and identify the safest next setup step. Do not modify files. +``` + +Expected survey result: + +- It may report that `.cf-studio/` and the SDLC kit are ready. +- It may report that there is no application code yet; that is normal for a fresh course repo. +- It may report that the artifact registry is empty and no PRD, ADR, DESIGN, DECOMPOSITION, or FEATURE exists yet. +- It may report whether the repo has an initial commit. +- It may recommend one of several next steps: make the initial commit, brainstorm intent, or write PRD/FEATURE. + +Use this course policy to interpret the survey: + +- If the survey reports missing Git `HEAD`, create the initial setup commit before continuing. +- If the survey recommends `cf-brainstorm` as the safest next step, accept that recommendation and continue to Module 3. +- If the survey recommends creating PRD or FEATURE immediately, treat that as a useful reminder that the artifact registry is empty, but do not skip the course path. Continue to Module 3 and run the brainstorm first so the first artifact is grounded in a human-approved Todo intent. + +Do not create technical plumbing just because it is absent; the agent creates it when implementation begins. Do not register codebase scan paths in Module 2: there are no course artifacts yet, so marker scanning is not actionable. The course handles traceability configuration later, after the Todo FEATURE exists and implementation is about to begin. + +5. Run a read-only readiness check for the next course stage. + +Claude Code prompt: + +```text +/cf-explore verify that this repo is ready to continue to the Todo brainstorm and SDLC artifact chain. +Check only setup readiness: .cf-studio initialization, sdlc kit installation, generated host integration, valid git HEAD, and docs/course-notes.md. +Do not modify files. +Return: +- PASS if the repo is ready for brainstorm/artifact authoring +- SETUP BLOCKER only for issues that prevent Module 3 from running +- DEFERRED if the issue matters later but does not block brainstorm or SDLC artifacts +``` + +Codex prompt: + +```text +$cf-explore verify that this repo is ready to continue to the Todo brainstorm and SDLC artifact chain. +Check only setup readiness: .cf-studio initialization, sdlc kit installation, generated host integration, valid git HEAD, and docs/course-notes.md. +Do not modify files. +Return: +- PASS if the repo is ready for brainstorm/artifact authoring +- SETUP BLOCKER only for issues that prevent Module 3 from running +- DEFERRED if the issue matters later but does not block brainstorm or SDLC artifacts +``` + +Expected readiness interpretation: + +- Missing initial Git commit is a `SETUP BLOCKER`; native sub-agent dispatch can fail when `git rev-parse HEAD` has no valid commit. +- Missing `.cf-studio/`, missing SDLC kit, or missing generated host integration is a `SETUP BLOCKER`. + +Healthy readiness output should look like this in substance: + +```text +Setup Readiness Report — Module 3 + +Check Result Evidence +-------------------------- ------ ------------------------------------------------- +.cf-studio initialization PASS .cf-studio/ + core.toml [[kits]] sdlc + artifacts.toml +SDLC kit installation PASS kits/sdlc/ subdirs; all artifact kinds + workflows +Generated host integration PASS .cf-studio/.gen/ with AGENTS.md + SKILL.md +Git HEAD PASS valid commit on current branch; no detached HEAD +docs/course-notes.md PASS exists, writable; section headers present (body empty) + +Overall: PASS — ready for the Todo brainstorm and SDLC artifact chain (Module 3). +No SETUP BLOCKER. No DEFERRED items. +``` + +If the host offers next options after the PASS, choose the brainstorm route. Do not choose direct PRD/FEATURE generation yet; the next course step is the human-guided Todo brainstorm. + +6. Do not implement backend or UI product code in Module 2 yet. Greenfield SDLC work is design-first: implementation with `cf-sdlc-implement` starts only after PRD, ADR, DESIGN, DECOMPOSITION, and FEATURE exist, and that implementation also creates the project shell (`package.json`, `ui/`, `src/server/`, `.gitignore`, and the package scripts). + +7. After setup, the repo holds just Constructor Studio and your notes: + +```text +.cf-studio/ +docs/ + course-notes.md +``` + +Generated host-integration directories (such as `.claude/`, `.agents/`, `.codex/`) are also present. The agent creates `package.json`, `src/server/`, `tests/`, `ui/`, and the package scripts (`dev:api`, `dev:ui`, `test`, `typecheck`, `build`) when FEATURE-driven implementation begins in Module 4. + +8. There is no command contract to record yet. The package scripts are created by the agent during implementation in Module 4. Before Module 3, the important point is that setup, activation, and readiness checks passed; the app and its commands come later, from the FEATURE. + +### Lesson 2.4. Activation Rubric + +Use this rubric to grade the activation and read-only responses you already saw in Lesson 2.3 — the `/cf` load report and the `cf-explore` survey and readiness output. If you opened a fresh chat, re-run `/cf` and one read-only `cf-explore` prompt first, then apply the rubric. + +A healthy activation: + +- gives a clear activation confirmation or workflow-aware acknowledgement, not a generic-assistant reply; +- stays read-only on the survey and readiness prompts and writes no files; +- references at least one real repo artifact or note (`docs/course-notes.md`, `.cf-studio/`, or `src/`); +- names one bounded next step, or one tight clarification question. + +It may name different "safest" next steps in different hosts. That is acceptable here: you are testing read-only routing and repo awareness, not delegating the course sequence. + +Interpretation rule: + +- If the response suggests writing PRD or FEATURE directly, record the suggestion, then still continue to the Module 3 brainstorm. The course's canonical sequence is: setup, read-only survey, brainstorm, then SDLC artifacts. +- If the response suggests backend code first, defer it until after the brainstorm and artifact chain. + +Short activation rubric: + +- Good: read-only behavior, explicit mention of a real repo artifact, no file writes, and one bounded next step or one tight clarification question. +- Bad: writes files, ignores the read-only instruction, or replies like a generic assistant with no `cf` workflow behavior. + +Checkpoint: + +- `docs/course-notes.md` contains one activation note and one read-only analysis result. +- `docs/course-notes.md` lists one good activation signal and one bad activation signal taken from the actual response you saw. + +### Lesson 2.5. Routing And Control Plane: Operator Summary + +You do not need the full internals on day one. You do need the operator rules that prevent bad turns. + +- The `cf` skill loads its core rules at session start (the load report) before any workflow work and gates what can run safely in this repo. +- Intent routing offers the matching `cf-*` skill, so ask for one thing at a time and phrase the request clearly. +- A request such as `find the bug and fix it` goes to `cf-coding`, which reviews first and then applies bounded fixes through its review-fix loop. +- If your input is very large, ask `cf-explore` to summarize or split it into smaller review units before you continue, and use `cf-plan` only when the work itself truly needs phased execution. +- Write permissions, git behavior, and sub-agent behavior are controlled separately; do not assume that because one gate is open, all gates are open. +- The `cf-coding`, `cf-write-docs`, and `cf-write-skills` workflows open with optional explore and brainstorm gates before authoring or reviewing; skip them (the default) when the task is already clear, or use them for unfamiliar or ambiguous work. +- Keep context lean: when the next step does not need the current chat context, run `/clear` or open a new chat. Everything the course relies on lives on disk — the SDLC artifacts, `plan.toml` and phase files, the saved brainstorm, and `docs/course-notes.md` — so a fresh session loses nothing. After any reset, re-activate with `/cf` (and on Codex, re-send `disable autonomous mode`) before continuing, because activation is per session. + +Under-the-hood glossary: + +- The deeper gate and state glossary lives in Appendix D. Read it when you need to reconcile routing, size gates, or control-plane variables against source truth. + +Mini-lab: + +1. In `docs/course-notes.md`, add a short table with three rows: `cf-explore`, `cf-plan`, `cf-coding`. +2. For each row, write one sentence for when it is the right route. +3. Add one sentence explaining how `cf-coding` both finds and fixes through its review-fix loop. + +### Lesson 2.6. Optional Source-Truth Sanity Check + +Use this only as a lightweight safety check during the core path when command wording or routing behavior looks inconsistent in your current host. Do not turn it into a full audit unless something is actually off. + +Do this when: + +- command spelling looks inconsistent; +- routing or gate behavior in the host does not match the course; +- you need to clarify one live workflow choice before continuing. + +Suggested prompt. + +Claude Code prompt: + +```text +/cf-explore compare the specific Constructor Studio command or routing wording I am about to use with the current repo-visible source truth for version 1.0.0. Return only the learner-safe phrasing I should use next and any explicit exclusions. Do not modify files. +``` + +Codex prompt: + +```text +$cf-explore compare the specific Constructor Studio command or routing wording I am about to use with the current repo-visible source truth for version 1.0.0. Return only the learner-safe phrasing I should use next and any explicit exclusions. Do not modify files. +``` + +Formal source-truth reconciliation for teaching, reuse, or governance happens later in Module 10.3. During the core Todo path, record only the corrections that materially affect the current repo. + +## Module 3. Create The SDLC Artifact Chain And Plan The Todo Work + +### Module 3 Host Gate + +Before you start artifact authoring, prove that your host preserves Constructor Studio routing: + +1. Activate Constructor Studio: `/cf` in Claude Code, or `$cf` in Codex. +2. Run one read-only `cf-explore` prompt and confirm it does not write files. +3. Run the `cf-brainstorm` prompt in Lesson 3.1 and confirm it behaves as brainstorming, not generic implementation. +4. Ask for a write-capable artifact prompt only after the host shows or respects an explicit write-confirmation boundary. + +If the host you chose does not preserve activation, read-only analysis, brainstorming, and write-confirmation boundaries, regenerate that host integration, reopen or reload the host, and rerun the gate. If it still fails, use another generated host that passes the gate before continuing. + +### Lesson 3.1. Pick The Right Workflow + +Use this decision table. + +| Situation | Use | +|---|---| +| The idea is fuzzy | `cf-brainstorm` | +| You need the SDLC artifact chain | `cf-sdlc-doc-prd`, `cf-sdlc-doc-adr`, `cf-sdlc-doc-design`, `cf-sdlc-decompose`, `cf-sdlc-doc-feature` | +| The task is multi-step, risky, or multi-file | `cf-plan` | +| The scope is approved and you are writing or changing code | `cf-coding` (or `cf-sdlc-implement` for FEATURE → code with `@cpt-*` traceability) | +| You need review, validation, or explanation | the same specialized skill (each reviews through its review-fix loop); `cf-explain` for walkthroughs, `cf-write-skills` for prompt/workflow/agent files | + +Do this exercise in chat. + +Claude Code prompt: + +```text +/cf-brainstorm I want to learn Constructor Studio by building a very small Todo app. +The app should have a TypeScript HTTP API and a React UI. +As a user, I should be able to list todos, create one with a title, toggle completion, and delete it. +Keep the project local, simple, reviewable, and suitable for SDLC artifacts, validation, and traceability practice. +Help me brainstorm the PRD-level product requirements first: actors, goals, functional requirements, non-goals, constraints, acceptance criteria, and product scope boundaries. Do not plan implementation yet. +End this brainstorm session by saving or summarizing the decisions only. Do not continue into PRD generation, artifact writing, planning, or implementation in this turn. +``` + +Codex prompt: + +```text +$cf-brainstorm I want to learn Constructor Studio by building a very small Todo app. +The app should have a TypeScript HTTP API and a React UI. +As a user, I should be able to list todos, create one with a title, toggle completion, and delete it. +Keep the project local, simple, reviewable, and suitable for SDLC artifacts, validation, and traceability practice. +Help me brainstorm the PRD-level product requirements first: actors, goals, functional requirements, non-goals, constraints, acceptance criteria, and product scope boundaries. Do not plan implementation yet. +End this brainstorm session by saving or summarizing the decisions only. Do not continue into PRD generation, artifact writing, planning, or implementation in this turn. +``` + +Expected result: + +- A PRD-focused brainstorm, not an implementation plan. +- A brainstorm panel offer. +- A proposed expert panel and seed topic. +- A wrap-up menu that lets you approve, iterate, discard, or continue into the next workflow with resolved inputs. +- The session stops after saved or summarized brainstorm decisions. +- No implementation yet. + +The interaction runs in this order: (1) the brainstorm panel offer, (2) a one-time sub-agent approval, (3) the proposed expert panel. + +1. Brainstorm panel offer. It reads roughly "Want a brainstorm panel? I'll assemble a 3-6 expert panel for cross-discipline pushback…", with reply grammar `yes` / `no` / `save` (plus optional modifiers such as `:N` for a round cap, `mode=fan-out`, or `mode=single-agent`). Reply `save` for this course so the transcript, `state.json`, and final `design.md` persist under `.cf-studio/.cache/brainstorm/...`: + +```text +save +``` + +If `save` is not offered because the host is chat-only, reply `yes` and rely on the wrap-up approval handoff. If the session has already moved past the offer with no save path, finish the brainstorm and copy the approved wrap-up summary into `docs/course-notes.md` as fallback evidence. + +2. Sub-agent approval (asked once per session). Approve so the facilitator and panel sub-agents run natively: + +```text +1 +``` + +3. Proposed expert panel and seed topic. The menu offers `start`, `seed:`, `drop E{N}`, `swap E{N}:`, `add:`, or `wrap`. Use the simplest path unless you see a real gap — reply `start` to begin round 1: + +```text +start +``` + +The git-commit-mode question does not appear during brainstorm — its sub-agents are read-only. You are asked to choose `commit` / `stage` / `none` later, at the first write-capable workflow (for example PRD authoring); choose `commit` for this course so write-capable sub-agents have an explicit git boundary. That choice never overrides write gates: every file write still needs the workflow's write release and your explicit confirmation. + +During the brainstorm rounds, keep these course constraints non-negotiable: + +- the PRD scope must still cover list, create, toggle, and delete as product capabilities; +- the artifact chain is still PRD -> ADR + DESIGN -> DECOMPOSITION -> FEATURE before implementation; +- storage is local and simple, preferably in-memory for the first backend slice unless you intentionally approve persistence; +- no auth, multi-user behavior, routing, tags, due dates, priority, editing titles after creation, deployment, or database work. + +If a panel tries to plan the implementation slice, drop delete, skip ADR/DESIGN, or delay the SDLC chain until after code, do not accept that default. Redirect the round back to PRD-level product requirements and scope boundaries. + +Common Round 1 answer when the defaults preserve all four Todo operations: + +```text +accept all +then: W +``` + +Common Round 1 answer when the panel tries to defer delete or skip SDLC layers: + +```text +E1Q1: keep this brainstorm at PRD level; implementation planning comes later through DESIGN, DECOMPOSITION, and FEATURE +E2Q1: include list, create, toggle, and delete in PRD scope; do not defer delete +E3Q1: accept +E4Q1: accept +then: W +``` + +Use `then: W` when the first round has already captured product scope, boundaries, actors, and acceptance direction. Pick another numbered topic only if a PRD requirement or boundary is still unresolved. + +At the brainstorm wrap-up, approve the resolved inputs if they match the Todo course scope, but do not continue into PRD generation in the same turn. If the workflow offers a handoff into the next generate step, stop after saving or summarizing the brainstorm decisions. Record the saved brainstorm cache path if save mode was used, or record the approved wrap-up summary in `docs/course-notes.md` if the session was chat-only. The brainstorm output becomes the original input evidence for PRD generation; it is not the governing implementation artifact. + +If the host asks whether to continue into PRD generation immediately, answer: + +```text +stop after saving the brainstorm decisions; do not generate PRD yet +``` + +Context reset (optional): the brainstorm decisions are saved on disk, and PRD authoring reads them from there. You can `/clear` or open a new chat before the artifact chain to keep context lean — then re-activate (`/cf`; on Codex also re-send `disable autonomous mode`). + +### Lesson 3.2. Create The SDLC Artifact Chain + +The SDLC kit is the governing process for this course. Its pipeline is: + +```text +PRD -> ADR + DESIGN -> DECOMPOSITION -> FEATURE -> CODEBASE -> TESTING / REVIEW +``` + +Each layer transforms the previous layer: + +- PRD captures WHAT: actors, capabilities, requirements, use cases, constraints, non-goals. +- ADR captures key architecture decisions and rationale. +- DESIGN captures HOW: components, interfaces, data model, API shape, sequences, constraints. +- DECOMPOSITION breaks DESIGN into ordered feature scope with dependencies. +- FEATURE captures implementable behavior as CDSL (Constructor DSL) flows, algorithms, states, definitions of done, and acceptance criteria. +- CODEBASE implements FEATURE, runs tests/build/review, and keeps traceability through scope markers plus per-instruction block markers when FULL traceability mode is active. +- TESTING / REVIEW validates behavior, markers, references, and semantic correctness. + +Create the artifacts from the brainstorm-derived Todo input brief. Use `cf` if that is your host alias; the SDLC kit docs also show `cf-studio` for some kit-specific surfaces. + +Artifact write pattern: send the authoring prompt for the next artifact directly (for example `cf-sdlc-doc-prd` for the PRD). The skill runs its own preflight, reports the exact target path and write scope, and waits for your approval before writing — there is no separate `cf-explore` step. Include `Approved write scope:` in the prompt, or approve the host's write-confirmation turn for those exact paths. + +What the authoring skill reports for an empty registry: + +- It may report `Semantic: FAIL` because `artifacts = []` and no PRD exists yet. That is expected at this exact point in the course; it means the SDLC chain has not started, not that setup failed. +- Treat the reported PRD path as the source of truth. In a fresh `TodoCourse` run this may be `docs/todocourse/PRD.md`; in another repo it may differ. +- If the host offers a menu such as "continue in this session", "fix prompt", or "plan prompt", do not let it auto-create the artifact from a vague menu choice. Continue with the explicit PRD generation prompt below, using the exact path the skill reported. +- Record the reported path and the empty-registry status in `docs/course-notes.md`. + +### Lesson 3.2a. PRD, ADR, And DESIGN + +During artifact generation, Constructor Studio may ask where to keep the mandatory author plan: + +```text +Reply enter or memory for in-memory plan (default), or disk to also save a Markdown plan pack under .cf-studio/.cache/generate-plans/. +``` + +For this course, reply: + +```text +memory +``` + +Use `disk` only if you intentionally want to inspect or preserve the generated author plan files across a long session. The normal course path keeps the plan in memory and writes only the approved SDLC artifacts. + +PRD authoring is the first write-capable workflow, so this is where the git-commit-mode question appears: Constructor Studio asks how sub-agents should handle git for the files they write this session — `commit` / `stage` / `none`. Choose `commit` for this course: + +```text +1 +``` + +This is asked once per session. If you ran the Module 3 brainstorm, sub-agent dispatch was already approved there; if you skipped it, you are asked to approve sub-agents here instead (reply `1`). + +Before it writes, the authoring skill (the SDLC doc skills run through `cf-write-docs`) opens two optional gates, each a numbered menu — first an explore gate, then a brainstorm gate: + +```text +Before writing or reviewing docs, brainstorm ambiguous decisions or framing options with cf-brainstorm — or skip? Skip is the default when the approach is already clear. Reply with a number. +1 brainstorm +2 skip +``` + +Skip is the default. For this course you already ran a dedicated brainstorm in Module 3, so reply `2` (skip) at both gates here: + +```text +2 +``` + +Reply `1` (brainstorm) only to refine a genuinely ambiguous artifact — that launches `cf-brainstorm` with the offer from Lesson 3.1 (`yes` / `no` / `save`); prefer `save` so the decisions persist. Brainstorm separately per layer only when it helps: ADR + DESIGN when the architecture/design choices are still fuzzy, DECOMPOSITION or FEATURE when implementation order or acceptance boundaries are unclear. + +After writing, the skill runs its own review-fix loop — it does not ask how many iterations to run. It runs the deterministic gate (tests, lint, typecheck, build where applicable), then a semantic review, and asks you to approve fixes one finding at a time. Each approved fix is applied, the deterministic gate re-runs, and the review repeats; the loop stops and reports any remaining findings when no fix is applied (nothing approved or nothing applicable). You stay in control through the per-finding approval gate, not an iteration count. + +PRD. + +Let the agent find the saved brainstorm evidence inside the PRD generation turn. This keeps the copy-paste prompt self-contained. + +Claude Code prompt: + +```text +/cf-sdlc-doc-prd make PRD for the Todo app from the approved brainstorm wrap-up. +Approved write scope: +- the exact PRD path reported by the skill, for example docs/todocourse/PRD.md +Before writing, find the newest saved brainstorm session under .cf-studio/.cache/brainstorm that matches the Todo PRD/product-requirements brainstorm. +Use its design.md as the original input evidence and its state.json as supporting context. +Report the exact design.md and state.json paths you selected. +If no saved brainstorm session exists, stop and ask me to either run the brainstorm with save mode or provide the approved brainstorm wrap-up from chat. +Keep PRD at the WHAT layer: actors, capabilities, requirements, use cases, constraints, non-goals, risks, and success criteria. +Do not include API schema, React component design, implementation tasks, or code details in the PRD. +``` + +Codex prompt: + +```text +$cf-sdlc-doc-prd make PRD for the Todo app from the approved brainstorm wrap-up. +Approved write scope: +- the exact PRD path reported by the skill, for example docs/todocourse/PRD.md +Before writing, find the newest saved brainstorm session under .cf-studio/.cache/brainstorm that matches the Todo PRD/product-requirements brainstorm. +Use its design.md as the original input evidence and its state.json as supporting context. +Report the exact design.md and state.json paths you selected. +If no saved brainstorm session exists, stop and ask me to either run the brainstorm with save mode or provide the approved brainstorm wrap-up from chat. +Keep PRD at the WHAT layer: actors, capabilities, requirements, use cases, constraints, non-goals, risks, and success criteria. +Do not include API schema, React component design, implementation tasks, or code details in the PRD. +``` + +Validate PRD. + +Claude Code prompt: + +```text +/cf-sdlc-doc-prd validate PRD for the Todo app. Check structural, semantic, and reference quality. Do not modify code. +``` + +Codex prompt: + +```text +$cf-sdlc-doc-prd validate PRD for the Todo app. Check structural, semantic, and reference quality. Do not modify code. +``` + +Read the validation result before moving on: + +- classify one finding as blocker or non-blocker; +- cite the evidence that caused that classification; +- decide whether to revise the artifact or proceed; +- record the decision in `docs/course-notes.md`. + +ADR, then DESIGN. Author them in order with the two specialized SDLC skills: `cf-sdlc-doc-adr` first, then `cf-sdlc-doc-design`. + +ADR — Claude Code prompt: + +```text +/cf-sdlc-doc-adr make the ADR for the Todo app from the PRD. +Approved write scope: +- the exact ADR path reported by the skill, for example docs/todocourse/ADR/cpt-todocourse-adr-todo-architecture.md +ADR decision: TypeScript HTTP API backend plus Vite React client for this course. +Do not implement code. +``` + +ADR — Codex prompt: + +```text +$cf-sdlc-doc-adr make the ADR for the Todo app from the PRD. +Approved write scope: +- the exact ADR path reported by the skill, for example docs/todocourse/ADR/cpt-todocourse-adr-todo-architecture.md +ADR decision: TypeScript HTTP API backend plus Vite React client for this course. +Do not implement code. +``` + +DESIGN — Claude Code prompt: + +```text +/cf-sdlc-doc-design make the DESIGN for the Todo app from the PRD and ADR. +Approved write scope: +- the exact DESIGN path reported by the skill, for example docs/todocourse/DESIGN.md +DESIGN must define the API boundary, Todo data model, UI/API interaction, local dev ports, validation approach, and traceability expectations. +Do not implement code. +``` + +DESIGN — Codex prompt: + +```text +$cf-sdlc-doc-design make the DESIGN for the Todo app from the PRD and ADR. +Approved write scope: +- the exact DESIGN path reported by the skill, for example docs/todocourse/DESIGN.md +DESIGN must define the API boundary, Todo data model, UI/API interaction, local dev ports, validation approach, and traceability expectations. +Do not implement code. +``` + +Validate ADR and DESIGN. + +Claude Code prompt: + +```text +/cf-sdlc-doc-design validate ADR and DESIGN against the PRD and SDLC kit rules. Do not modify code. +``` + +Codex prompt: + +```text +$cf-sdlc-doc-design validate ADR and DESIGN against the PRD and SDLC kit rules. Do not modify code. +``` + +Checkpoint: + +- `docs/course-notes.md` records PRD, ADR, and DESIGN paths. +- `docs/course-notes.md` explains one thing that belongs in PRD and one implementation detail that must stay out. +- `docs/course-notes.md` explains one ADR decision and one DESIGN detail that must not be placed in PRD. +- You revised blocker findings before continuing, or explicitly recorded why findings are non-blocking. + +### Lesson 3.2b. DECOMPOSITION And FEATURE + +DECOMPOSITION. + +Claude Code prompt: + +```text +/cf-sdlc-decompose decompose the Todo DESIGN into ordered feature scope. +Approved write scope: +- the exact DECOMPOSITION path reported by the skill, for example docs/todocourse/DECOMPOSITION.md +Include at least one feature for Todo CRUD behavior that covers list, create, toggle, and delete. +Keep dependencies explicit and implementation units small. +Do not implement code. +``` + +Codex prompt: + +```text +$cf-sdlc-decompose decompose the Todo DESIGN into ordered feature scope. +Approved write scope: +- the exact DECOMPOSITION path reported by the skill, for example docs/todocourse/DECOMPOSITION.md +Include at least one feature for Todo CRUD behavior that covers list, create, toggle, and delete. +Keep dependencies explicit and implementation units small. +Do not implement code. +``` + +Validate DECOMPOSITION. + +Claude Code prompt: + +```text +/cf-sdlc-decompose validate DECOMPOSITION against DESIGN and PRD. Check coverage, dependencies, IDs, and references. Do not modify code. +``` + +Codex prompt: + +```text +$cf-sdlc-decompose validate DECOMPOSITION against DESIGN and PRD. Check coverage, dependencies, IDs, and references. Do not modify code. +``` + +FEATURE. + +Recommended course convention: put FEATURE artifacts under `docs/todocourse/features/`. This keeps implementable feature specs separate from system-level PRD, ADR, DESIGN, and DECOMPOSITION artifacts. + +Claude Code prompt: + +```text +/cf-sdlc-doc-feature make FEATURE for todo-crud from DECOMPOSITION and DESIGN. +Approved write scope: +- the exact FEATURE path reported by the skill, for example docs/todocourse/features/todo-crud.md +The FEATURE must include CDSL actor flows for list, create, toggle, and delete; processing algorithms; Todo state behavior where relevant; definitions of done; acceptance criteria; and upstream references. +Preserve the SDLC FEATURE template structure, including the top-level `featstatus` ID and the parent DECOMPOSITION feature reference. +Do not implement code. +``` + +Codex prompt: + +```text +$cf-sdlc-doc-feature make FEATURE for todo-crud from DECOMPOSITION and DESIGN. +Approved write scope: +- the exact FEATURE path reported by the skill, for example docs/todocourse/features/todo-crud.md +The FEATURE must include CDSL actor flows for list, create, toggle, and delete; processing algorithms; Todo state behavior where relevant; definitions of done; acceptance criteria; and upstream references. +Preserve the SDLC FEATURE template structure, including the top-level `featstatus` ID and the parent DECOMPOSITION feature reference. +Do not implement code. +``` + +Validate FEATURE. + +Claude Code prompt: + +```text +/cf-sdlc-doc-feature validate FEATURE todo-crud for CDSL structure, semantic completeness, upstream references, definitions of done, and implementation readiness. Do not modify code. +``` + +Codex prompt: + +```text +$cf-sdlc-doc-feature validate FEATURE todo-crud for CDSL structure, semantic completeness, upstream references, definitions of done, and implementation readiness. Do not modify code. +``` + +Checkpoint: + +- `docs/course-notes.md` records DECOMPOSITION and FEATURE paths. +- `docs/course-notes.md` explains why ordered implementation units belong in DECOMPOSITION. +- `docs/course-notes.md` explains why CDSL flows, algorithms, states, and definitions of done belong in FEATURE. +- `docs/course-notes.md` lists one thing that must stay out of FEATURE because it belongs in DESIGN, ADR, PRD, or CODEBASE. + +### Lesson 3.2c. Validate The Artifact Chain + +Expected artifact locations are the paths the skill reports and registers in `.cf-studio/config/artifacts.toml`. In a fresh `TodoCourse` run, they may look like: + +- `docs/todocourse/PRD.md` +- `docs/todocourse/ADR/cpt-todocourse-adr-*.md` +- `docs/todocourse/DESIGN.md` +- `docs/todocourse/DECOMPOSITION.md` +- `docs/todocourse/features/*.md` + +Deterministic validation examples, using the fresh `TodoCourse` shape: + +```bash +cfs validate --artifact docs/todocourse/PRD.md +cfs validate --artifact docs/todocourse/ADR/cpt-todocourse-adr-todo-architecture.md +cfs validate --artifact docs/todocourse/DESIGN.md +cfs validate --artifact docs/todocourse/DECOMPOSITION.md +cfs validate --artifact docs/todocourse/features/todo-crud.md +cfs validate --local-only +``` + +Always replace the sample paths with the exact paths registered in your repo before running the commands. Validate every ADR file separately; the sample ADR and FEATURE paths are examples only. When `cfs toc` / `cfs validate-toc` is available in your installed version and required by the artifact rules, update the table of contents before marking an artifact ready. + +Checkpoint: + +- `docs/course-notes.md` records the paths of PRD, ADR, DESIGN, DECOMPOSITION, and FEATURE. +- `docs/course-notes.md` records validation results for each artifact layer. +- `docs/course-notes.md` records one blocker/non-blocker classification from artifact validation and the decision it caused. +- The FEATURE artifact, not the brainstorm cache or wrap-up summary, is now the governing artifact for implementation. +- If the kit generated different artifact paths, record those paths and use them consistently from here onward. + +Context reset (optional): the artifact chain is on disk and the plan reads the FEATURE from `.cf-studio/config/artifacts.toml`. You can `/clear` or start a new chat before planning — then re-activate (`/cf`; on Codex also re-send `disable autonomous mode`). + +### Lesson 3.3. Create A Plan + +Now create a plan for the Todo app work. + +Pre-plan checkpoint: + +- Confirm the SDLC artifact chain exists and the Todo FEATURE is validated or has only explicitly accepted non-blocking issues. +- Confirm the Todo FEATURE is the governing artifact for implementation; the brainstorm cache or wrap-up summary is only the original input evidence. +- Confirm the bounded change target for the first phase: one backend/API slice first, then one React UI slice, then validation and review. +- Treat scope/content approval and later file-write approval as separate decisions. + +Claude Code prompt: + +```text +/cf-plan create a small implementation plan for the Todo FEATURE artifact. +Treat the registered Todo FEATURE path from `.cf-studio/config/artifacts.toml` as the governing artifact. +Assume the first phase is a bounded backend/API slice, the second phase is a bounded React UI slice, and the final phase is validation plus review. +The first phase must also create the project shell (package.json, dependencies, the dev:api/dev:ui/test/typecheck/build scripts, .gitignore, root tsconfig, and the Vite ui/) before or with the backend code, since the app is built here from the FEATURE. +Preserve SDLC kit traceability at the artifact level. Defer code marker and codebase scan-root decisions until implementation begins. +The plan must build one TypeScript backend/API slice and one React UI slice. +Use the actual course repo shape: +- backend/API files belong under src/server/ and tests/ +- React UI files belong under ui/src/ +- do not invent backend/src/ or frontend/src/ directories +Keep phases small. Include validation and review evidence. +Do not implement yet. +``` + +Codex prompt: + +```text +$cf-plan create a small implementation plan for the Todo FEATURE artifact. +Treat the registered Todo FEATURE path from `.cf-studio/config/artifacts.toml` as the governing artifact. +Assume the first phase is a bounded backend/API slice, the second phase is a bounded React UI slice, and the final phase is validation plus review. +The first phase must also create the project shell (package.json, dependencies, the dev:api/dev:ui/test/typecheck/build scripts, .gitignore, root tsconfig, and the Vite ui/) before or with the backend code, since the app is built here from the FEATURE. +Preserve SDLC kit traceability at the artifact level. Defer code marker and codebase scan-root decisions until implementation begins. +The plan must build one TypeScript backend/API slice and one React UI slice. +Use the actual course repo shape: +- backend/API files belong under src/server/ and tests/ +- React UI files belong under ui/src/ +- do not invent backend/src/ or frontend/src/ directories +Keep phases small. Include validation and review evidence. +Do not implement yet. +``` + +When `cf-plan` starts it first opens an explore/brainstorm gate (`Before assessing scope, explore project resources or brainstorm decisions — or skip straight to assessment? Reply with a number.`, options `1 explore` / `2 brainstorm` / `3 skip`). The FEATURE already defines the work, so reply `3` (skip). + +Expected result: + +- A plan directory under `.cf-studio/.plans/` when plan writes are available. +- `plan.toml` as the canonical manifest. +- Supporting `brief-*.md` and `phase-*.md` files. +- A next-phase execution prompt or equivalent "run this phase next" instruction. +- The response explicitly reports the created plan path. + +If the plan workflow asks how completed plans should be handled (lifecycle: `gitignore` / `cleanup` / `archive` / `manual`), choose: + +```text +gitignore +``` + +This keeps the generated plan files available locally while `.cf-studio/.plans/` remains out of version control. This is the recommended course path: the student can inspect `plan.toml`, briefs, and phase files throughout the course without committing temporary planning artifacts. + +Before confirming plan file writes, read the decomposition preview. If it proposes output paths like `backend/src/...` or `frontend/src/...`, do not answer `y` yet. Correct the plan in chat and require the repo shape from this lesson: `src/server/`, `tests/`, and `ui/src/`. + +After the manifest and briefs are written, the plan workflow asks how to produce the compiled phase files: + +```text +Brief package prepared (plan.toml + N briefs, 0/N phase files) — choose how to produce phase files: 1 inline (uses this chat's budget); 2 prompts (skips validation); 3 subagents (needs sub-agent approval); 4 stop (keep briefs). Reply with a number. +``` + +For this course, choose: + +```text +3 +``` + +This runs `cf-phase-compiler` subagents for each brief. It keeps the main chat focused and lets each phase file be compiled from its own brief. After the subagents finish, confirm that `phase-01-*.md`, `phase-02-*.md`, and `phase-03-*.md` exist under the plan directory before moving to execution. + +When the plan passes self-validation and the workflow asks for the next action, choose: + +```text +1 +``` + +This runs a dedicated `/cf-analyze` review of the plan before execution. Treat this as the plan gate: execute phase 1 only after the review has no blockers or after you explicitly accept any non-blocking findings. + +If the host returns a chat-only plan instead of plan files, treat that as a fallback, not equal plan truth. Ask for a file-backed plan when possible. + +Claude Code prompt: + +```text +/cf-plan restate this Todo plan as a canonical plan with plan.toml, brief files, and phase files if the host can write them. Do not implement yet. +``` + +Codex prompt: + +```text +$cf-plan restate this Todo plan as a canonical plan with plan.toml, brief files, and phase files if the host can write them. Do not implement yet. +``` + +If plan files still cannot be produced, copy the next-phase prompt into `docs/course-notes.md` and record that no canonical plan artifacts were created yet. + +If the path gets lost, recover the newest manifest from the repo root: + +```bash +find .cf-studio/.plans -name plan.toml -exec ls -t {} + | head -n 1 +``` + +Open the plan manifest and inspect: + +- manifest path; +- phase order; +- brief files; +- phase files; +- next phase prompt; +- inputs; +- outputs; +- status; +- acceptance criteria. + +Checkpoint: + +- Paste the plan path into `docs/course-notes.md`. +- Write the next phase you would execute and why. + +### Lesson 3.4. Plan Lifecycle States + +A plan can be valid even when not every generated file is present forever. + +Know these `plan.execution_status` values: + +- `not_started`: plan exists but execution has not begun. +- `briefs_only`: planning emitted briefs but not compiled phase files yet. +- `prompts_emitted`: prompts exist for downstream execution; compiled phase files may not be present. +- `in_progress`: execution has started. +- `failed`: execution or validation failed and needs triage. +- `done`: the planned work reached its terminal state. + +Also know these `plan.lifecycle_status` values: + +- `pending`: lifecycle handling has not started. +- `ready`: lifecycle action is ready to run. +- `in_progress`: lifecycle action is currently running or was interrupted mid-action. +- `done`: lifecycle action completed successfully. +- `failed`: lifecycle action failed and needs triage. +- `partial`: cleanup completed only partly; keep the receipt and inspect what remains. +- `manual_action_required`: manual lifecycle work is required before the plan can be treated as closed. + +Lifecycle cleanup can intentionally remove `brief-*`, `phase-*`, or `out/` files after the plan is finished. Lifecycle archive can move the plan under `.cf-studio/.plans/.archive/...`. + +Evidence rule: + +- Active plan with compiled phases: cite `plan.toml`, relevant `brief-*`, and relevant `phase-*`. +- `briefs_only` or `prompts_emitted`: cite `plan.toml`, emitted prompts/briefs, and explain that phase files were not generated yet. +- Cleanup: cite the terminal `plan.toml` receipt and note that compiled files were intentionally removed. +- Archive: cite the archived plan path or `active_plan_dir` / archive reference that points to it. + +Do not treat every missing `phase-*.md` as failure. Treat it as failure only when the manifest says compiled phases should exist and there is no lifecycle explanation. + +### Lesson 3.5. Execute One Compiled Phase As The Canonical Work Unit + +In Constructor Studio, the compiled `phase-*.md` file is the canonical work unit. Do not execute from chat memory when a compiled phase exists. + +Do this: + +1. Open `plan.toml`. +2. Confirm `plan.execution_status`, `plan.lifecycle_status`, and each `phases[].status`. +3. Select the next ready phase from the manifest state, not from memory. +4. Open only that `phase-*.md` file and treat it as the authoritative instructions for the phase. +5. If your host offers guarded same-chat native execution for compiled phases, use that for the selected phase. +6. If same-chat native execution is unavailable, generate or use the new-chat startup prompt contract: the new chat must read `plan.toml`, resolve the next phase from manifest state, verify dependencies and outputs, update status through the phase-runner contract, then execute the selected phase file. +7. Treat `cfs delegate` as an optional advanced branch only when you explicitly choose RalphEx-style delegated execution: + +```bash +cfs delegate ".cf-studio/.plans/todo-implementation-20260527" +``` + +Do not make `cfs delegate` the default Todo course execution path. +8. After execution, reopen `plan.toml` and record the status progression from disk. +9. Save the emitted next-phase prompt into `docs/course-notes.md`. + +Use only the execution surface your installed Studio version and host actually expose. Record which one you used: guarded same-chat native execution, new-chat startup prompt execution, or optional `cfs delegate` handoff. + +New-chat startup prompt when same-chat native execution is unavailable. + +Claude Code prompt: + +```text +I have a Constructor Studio execution plan ready at: + .cf-studio/.plans/todo-implementation-20260527/plan.toml + +Please read the plan manifest, then execute the next ready phase. +Treat plan.toml on disk as the source of truth for phase status. +Resolve the target phase from the manifest state unless I explicitly name a phase. +Verify dependencies, output paths, and lifecycle-state exceptions before executing. +Read only the selected phase file after manifest resolution. +Follow the phase file exactly; it is self-contained and authoritative. +Update plan.toml with the resulting phase status and aggregate execution state. +After completion, report results and generate the prompt for the next phase. +``` + +Codex prompt: + +```text +I have a Constructor Studio execution plan ready at: + .cf-studio/.plans/todo-implementation-20260527/plan.toml + +Please read the plan manifest, then execute the next ready phase. +Treat plan.toml on disk as the source of truth for phase status. +Resolve the target phase from the manifest state unless I explicitly name a phase. +Verify dependencies, output paths, and lifecycle-state exceptions before executing. +Read only the selected phase file after manifest resolution. +Follow the phase file exactly; it is self-contained and authoritative. +Update plan.toml with the resulting phase status and aggregate execution state. +After completion, report results and generate the prompt for the next phase. +``` + +Status rule: + +- Use the manifest statuses exactly as written on disk: `pending`, `in_progress`, `done`, or `failed`. +- Do not invent alternate phase labels in your notes. +- Read the status changes from `plan.toml` after execution. Do not infer them from chat memory. + +Checkpoint: + +- `docs/course-notes.md` records the selected `phase-*.md` path, the exact `phases[].status` evidence copied from `plan.toml` before and after execution, and the next-phase prompt. +- `docs/course-notes.md` also explains why that phase was the correct next phase based on the manifest state, not memory or guesswork. + +### Lesson 3.6. Recovery From A Bad Plan + +A bad plan is usually too broad, not evidence-based, or missing validation. + +If the plan tries to build everything in one step, recover with a read-only review first. + +Claude Code prompt: + +```text +/cf-plan review this plan for unsafe scope, missing validation, missing review evidence, and unclear Todo acceptance criteria. Do not modify files. +``` + +Codex prompt: + +```text +$cf-plan review this plan for unsafe scope, missing validation, missing review evidence, and unclear Todo acceptance criteria. Do not modify files. +``` + +Then ask for a narrower plan. + +Claude Code prompt: + +```text +/cf-plan revise the Todo implementation plan so the first phase only creates the backend/API model and operations, the second phase connects the React UI, and the final phase validates and prepares the handoff. +Keep the Todo FEATURE artifact as the governing artifact and preserve SDLC traceability markers. +``` + +Codex prompt: + +```text +$cf-plan revise the Todo implementation plan so the first phase only creates the backend/API model and operations, the second phase connects the React UI, and the final phase validates and prepares the handoff. +Keep the Todo FEATURE artifact as the governing artifact and preserve SDLC traceability markers. +``` + +Checkpoint: + +- Your plan has separate implementation, validation, and review points. + +## Module 4. Implement The TypeScript HTTP API Slice + +### Lesson 4.0. Pre-Implementation Command Gate + +You are now about to write product code. The backend implementation step creates the project shell (`package.json`, dependencies, the package scripts, `src/server/`, and the Vite `ui/`) along with the backend code, so confirm the plan for that first. + +The core path uses this command contract: + +```bash +npm run dev:api +npm run dev:ui +npm test +npm run typecheck +npm run build +``` + +`dev:api`, `typecheck`, and `build` must become real implementation/validation commands. The backend implementation step creates `package.json`, the dependencies, and these scripts. Do not start the backend slice without a plan to make them pass in or before the backend implementation write. + +If the planned TypeScript HTTP API and React client cannot be supported by the repo, do not invent a different core architecture mid-course. Stop, record the gap in `docs/course-notes.md`, and get approval for an alternate setup. + +Choose the implementation traceability mode now: + +- `FULL`: code will include Constructor Studio markers for implemented FEATURE flows, algorithms, states, and definitions of done; register codebase scan roots before writing product code. +- `DOCS-ONLY`: code stays free of Constructor Studio markers; keep traceability through artifacts, validation notes, and review evidence. + +For this course, prefer `FULL` if you want to practice marker scanning end to end. Choose `DOCS-ONLY` only if the goal of the run is artifact practice rather than code-marker practice. Record the choice in `docs/course-notes.md`. + +If you choose `FULL` and the implementation roots are not registered yet, do one configuration-only pass now. This is the first point where codebase scan roots are actionable: the FEATURE exists, the implementation plan exists, and product code is about to be written. + +Claude Code prompt: + +```text +/cf-coding update only .cf-studio/config/artifacts.toml so Constructor Studio can scan the Todo course implementation roots for the already-created Todo FEATURE. +Approved write scope: +- .cf-studio/config/artifacts.toml +Required outcomes: +- backend codebase scan root covers src/server TypeScript files +- frontend codebase scan root covers ui/src TypeScript and TSX files +- existing PRD, ADR, DESIGN, DECOMPOSITION, and FEATURE registrations remain unchanged +Do not create product code. +Do not implement Todo behavior. +After writing, report the exact codebase entries and the FEATURE path they support. +``` + +Codex prompt: + +```text +$cf-coding update only .cf-studio/config/artifacts.toml so Constructor Studio can scan the Todo course implementation roots for the already-created Todo FEATURE. +Approved write scope: +- .cf-studio/config/artifacts.toml +Required outcomes: +- backend codebase scan root covers src/server TypeScript files +- frontend codebase scan root covers ui/src TypeScript and TSX files +- existing PRD, ADR, DESIGN, DECOMPOSITION, and FEATURE registrations remain unchanged +Do not create product code. +Do not implement Todo behavior. +After writing, report the exact codebase entries and the FEATURE path they support. +``` + +### Lesson 4.1. Define The Backend/API Contract + +Before asking the agent to write code, confirm that the backend/API contract exists in the SDLC artifacts. + +The PRD should contain the user-visible requirements. DESIGN should contain the API and data model. FEATURE should contain CDSL flows, algorithms, states, definitions of done, and acceptance criteria. If these details are only in the brainstorm cache or wrap-up summary, stop and update the SDLC artifacts first. + +The Todo FEATURE should express this behavior, either directly or by reference to DESIGN: + +```markdown +## Backend/API Contract + +Todo: +- id: string +- title: string +- completed: boolean +- createdAt: string + +Operations: +- listTodos(): Todo[] +- createTodo(title: string): Todo +- toggleTodo(id: string): Todo +- deleteTodo(id: string): void + +HTTP API: +- GET /api/todos -> Todo[] +- POST /api/todos -> Todo +- PATCH /api/todos/:id/toggle -> Todo +- DELETE /api/todos/:id -> 204 + +Rules: +- title must not be blank. +- createTodo trims title. +- toggleTodo fails clearly when the id is unknown. +- deleteTodo is idempotent only if the existing project already uses that convention; otherwise unknown id should fail clearly. +``` + +Checkpoint: + +- The Todo FEATURE is the authoritative behavior boundary for implementation, tests, and semantic review. +- `docs/course-notes.md` records the FEATURE path and the IDs for list, create, toggle, delete, and related definitions of done. + +### Lesson 4.2. Execute The Backend/API Plan Phase + +Do not start a fresh implementation prompt here. Module 3 already created and reviewed the implementation plan; the compiled phase file is now the governing work unit. If you discover that the backend/API scope needs a new endpoint, rule, file area, or behavior that is not already covered by PRD, DESIGN, DECOMPOSITION, FEATURE, and the plan, stop and update the artifacts or plan first. + +Run the next ready compiled phase from the plan manifest. In the normal course path, this is phase 1: the TypeScript backend/API slice. + +Phase 1 also creates the project shell — `package.json`, dependencies, the `dev:api`/`dev:ui`/`test`/`typecheck`/`build` scripts, `.gitignore`, the root `tsconfig`, and the Vite `ui/` — before or alongside the backend code, exactly as the plan and FEATURE require. If your compiled phase 1 does not include this shell, update the plan before executing. + +Claude Code prompt: + +```text +I have a Constructor Studio execution plan ready at: + .cf-studio/.plans/implement-todo-crud/plan.toml + +Please read the plan manifest, then execute only phase 1: TypeScript Backend / API Slice. +Treat plan.toml on disk as the source of truth for phase status. +Verify dependencies, output paths, and lifecycle-state exceptions before executing. +Read only the selected phase file after manifest resolution. +Follow the phase file exactly; it is self-contained and authoritative. +Use the actual course repo shape: backend/API files under src/server/ and tests/, not backend/src/. +If the phase requires scope that is not documented in the SDLC artifacts or compiled phase file, stop and ask for an artifact/plan update instead of inventing behavior. +Update plan.toml with the resulting phase status and aggregate execution state. +After completion, report changed files, validation output, and the prompt for the next phase. +``` + +Codex prompt: + +```text +I have a Constructor Studio execution plan ready at: + .cf-studio/.plans/implement-todo-crud/plan.toml + +Please read the plan manifest, then execute only phase 1: TypeScript Backend / API Slice. +Treat plan.toml on disk as the source of truth for phase status. +Verify dependencies, output paths, and lifecycle-state exceptions before executing. +Read only the selected phase file after manifest resolution. +Follow the phase file exactly; it is self-contained and authoritative. +Use the actual course repo shape: backend/API files under src/server/ and tests/, not backend/src/. +If the phase requires scope that is not documented in the SDLC artifacts or compiled phase file, stop and ask for an artifact/plan update instead of inventing behavior. +Update plan.toml with the resulting phase status and aggregate execution state. +After completion, report changed files, validation output, and the prompt for the next phase. +``` + +If your plan path differs, replace `.cf-studio/.plans/implement-todo-crud/plan.toml` with the exact manifest path produced in Module 3. + +Expected result: + +- Phase 1 status in `plan.toml` is updated from disk evidence. +- The project shell (`package.json`, dependencies, scripts, `.gitignore`, `ui/`) is created as part of phase 1. +- Backend/API files are created only in the repo shape approved by the plan and artifacts. +- Tests, build, or documented behavior proof are run according to the phase file. +- The agent reports the next-phase prompt without executing phase 2 yet. + +If the agent tries to bypass the compiled phase and starts proposing a separate implementation pass, stop and redirect it to the plan manifest and phase file. + +Checkpoint: + +- `docs/course-notes.md` maps each changed backend/API file to at least one FEATURE flow, algorithm, state, or definition-of-done ID. + +### Lesson 4.3. Validate The Backend/API Slice + +Use the repo's normal validation command if it exists. Common examples: + +```bash +npm test +npm run test +npm run typecheck +npm run lint +``` + +Constructor Studio validation: + +```bash +cfs validate --local-only +``` + +If the repo is workspace-aware and all sources are reachable: + +```bash +cfs validate +``` + +Expected result: + +- You have validation output. +- Passing validation is not final approval. +- Validation evidence records the exact command, pass/fail result, and either a key output excerpt or a raw log path/reference. + +If the repo has no test suite or no standard validation command, do not invent a broad setup just to satisfy the course. Record a TDD exception, run the narrowest available checks, such as one targeted test file, a typecheck, a lint command, or a local `cfs validate` pass, require concrete behavior proof, then record the missing-test or missing-command gap as a follow-up risk. + +If validation fails, do not ask for a broad fix. Ask for a narrow triage. + +Claude Code prompt: + +```text +/cf-coding triage these Todo backend/API validation failures against the Todo FEATURE and DESIGN. +Return the smallest safe fix plan. Do not modify files. +``` + +Codex prompt: + +```text +$cf-coding triage these Todo backend/API validation failures against the Todo FEATURE and DESIGN. +Return the smallest safe fix plan. Do not modify files. +``` + +Checkpoint: + +- Paste the exact command, pass/fail result, and a short output excerpt or raw log reference into `docs/course-notes.md`. + +## Module 5. Implement The React UI Slice + +Context reset (optional): the backend slice is committed and the UI slice reads the FEATURE and plan from disk. A `/clear` or new chat here keeps context lean — re-activate (`/cf`; on Codex also re-send `disable autonomous mode`) first. + +### Lesson 5.1. Define The UI Behavior + +Confirm that this UI behavior exists in the Todo FEATURE and references the relevant DESIGN/API elements. If it does not, update FEATURE before generating UI code: + +```markdown +## UI Contract + +The React UI should let a user: +- see all todos; +- type a title; +- add a todo; +- toggle completed state; +- delete a todo. + +The UI should show a simple empty state when there are no todos. +The UI does not need authentication, routing, or persistence beyond the course scope unless the existing app already has those conventions. + +## Local Integration Contract + +- Local API base in development: `http://localhost:3001` +- Vite UI in development: `http://localhost:5173` +- Preferred UI request shape: relative `/api/...` calls from the browser, forwarded by Vite proxy to `http://localhost:3001` +- If the repo already uses a different documented integration convention, record that convention in `docs/course-notes.md` before generating UI code +``` + +Checkpoint: + +- The UI scope is bounded before generation begins. + +### Lesson 5.2. Generate The UI Slice + +Write boundary before generation: + +- Approve the UI contract and bounded product scope first. +- Then approve the exact file-write scope for the UI slice. `cf-sdlc-implement` reports the target files, validation commands, write scope, and required traceability coverage before it writes, so you approve those exact paths. + +Run generation. + +Claude Code prompt: + +```text +/cf-sdlc-implement implement the React UI slice for the Todo app from the Todo FEATURE artifact. +Approved write scope: +- ui/src/App.tsx +- ui/src/components/TodoList.tsx +- ui/src/api.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- if a UI test harness exists: npm test -- TodoList +- if no UI test harness exists: npm run typecheck, npm run build, and the smoke checklist in Lesson 5.3 +- npm run build +Scope: +- use the existing frontend conventions; +- connect to the Todo HTTP API shape already created; +- use the local integration contract: UI at http://localhost:5173 and API at http://localhost:3001 through Vite proxy or the repo's documented equivalent; +- implement only the FEATURE flows/definitions of done assigned to the UI slice; +- in FULL traceability mode, add or preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs; +- if the repo has a runnable UI test harness, write a failing targeted UI test first, implement the minimal change to pass, then refactor; +- if the repo does not have a UI test harness, do not approve `npm test -- TodoList`; record a TDD exception, run `npm run typecheck`, `npm run build`, and the smoke checklist in Lesson 5.3, then report the testing gap as follow-up; +- update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap; +- include only list, create, toggle, delete, and empty-state behavior; +- do not add authentication, routing, or deployment. +After writing, report changed files and validation steps. +``` + +Codex prompt: + +```text +$cf-sdlc-implement implement the React UI slice for the Todo app from the Todo FEATURE artifact. +Approved write scope: +- ui/src/App.tsx +- ui/src/components/TodoList.tsx +- ui/src/api.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- if a UI test harness exists: npm test -- TodoList +- if no UI test harness exists: npm run typecheck, npm run build, and the smoke checklist in Lesson 5.3 +- npm run build +Scope: +- use the existing frontend conventions; +- connect to the Todo HTTP API shape already created; +- use the local integration contract: UI at http://localhost:5173 and API at http://localhost:3001 through Vite proxy or the repo's documented equivalent; +- implement only the FEATURE flows/definitions of done assigned to the UI slice; +- in FULL traceability mode, add or preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs; +- if the repo has a runnable UI test harness, write a failing targeted UI test first, implement the minimal change to pass, then refactor; +- if the repo does not have a UI test harness, do not approve `npm test -- TodoList`; record a TDD exception, run `npm run typecheck`, `npm run build`, and the smoke checklist in Lesson 5.3, then report the testing gap as follow-up; +- update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap; +- include only list, create, toggle, delete, and empty-state behavior; +- do not add authentication, routing, or deployment. +After writing, report changed files and validation steps. +``` + +If the skill named different files or commands, replace every sample path and command above before sending the prompt. + +Expected result: + +- A React component or UI route. +- Connection to the Todo backend/API or a clearly bounded adapter. +- No unrelated UI redesign. + +If the project has no React setup, ask for a plan before adding one. + +Claude Code prompt: + +```text +/cf-plan the repo does not appear to have a React setup. Plan the smallest course-appropriate React UI setup for the Todo app, including validation and handoff evidence. Do not implement yet. +``` + +Codex prompt: + +```text +$cf-plan the repo does not appear to have a React setup. Plan the smallest course-appropriate React UI setup for the Todo app, including validation and handoff evidence. Do not implement yet. +``` + +Checkpoint: + +- `docs/course-notes.md` names the UI entry file or route and the backend/API contract or adapter it uses. + +### Lesson 5.3. Validate The Full Project Slice + +Run applicable commands: + +```bash +npm test +npm run typecheck +npm run lint +npm run build +cfs validate --local-only +``` + +Capture the exact command, pass/fail result, and either a key output excerpt or raw log reference in `docs/course-notes.md`. + +If some commands do not exist, do not add a new build or test stack just for the course. Record a TDD exception when a runnable test harness is missing, run the narrowest available checks, and record the missing validation surface as a follow-up gap. + +Run one concrete smoke procedure and record it in `docs/course-notes.md` or `docs/review-handoff.md`: + +1. Start the backend with `npm run dev:api`. +2. Start the UI with `npm run dev:ui`. +3. Open `http://localhost:5173`. +4. Confirm the UI can load the todo list through `/api/todos`. +5. Create one todo such as `Study Constructor Studio` and confirm it appears. +6. Toggle that todo and confirm the completed state changes without a page reload. +7. Delete that todo and confirm it disappears from the list. +8. Record `Step`, `Expected result`, `Observed result`, and the evidence location. + +Then run semantic review. + +Claude Code prompt: + +```text +/cf-coding review the Todo backend/API and React UI changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. +Focus on correctness, missing tests, scope creep, validation gaps, and review readiness. +Do not modify files. +``` + +Codex prompt: + +```text +$cf-coding review the Todo backend/API and React UI changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. +Focus on correctness, missing tests, scope creep, validation gaps, and review readiness. +Do not modify files. +``` + +Expected result: + +- Findings are separated from fixes. +- You know which findings are blockers. +- You know whether another bounded `cf-coding` pass is needed. + +Use this blocker rule: + +- Blocker: violates the Todo FEATURE or upstream SDLC artifacts, fails validation, breaks a core user flow, loses required traceability, or widens scope unsafely. +- Defer: non-blocking polish, optional cleanup, or follow-up work that does not break the agreed slice. + +Checkpoint: + +- You have validation output, review findings, and a decision: accept, fix, or defer. + +## Module 6. Fix Loop And Review Discipline + +### Lesson 6.1. Fix One Finding At A Time + +Do not ask the agent to "fix everything" unless the findings are clearly small and mechanical. For normal course work, fix one class of issue at a time. + +Write boundary before remediation: + +- First approve which findings are in scope for this fix pass. +- Then approve the exact file-write scope for the remediation. + +Claude Code prompt: + +```text +/cf-coding fix only the blocker findings from the Todo review. +Use the Todo FEATURE artifact as the governing implementation artifact, and check upstream DESIGN/DECOMPOSITION/PRD when a fix changes behavior or architecture. +Finding IDs/text: +- BLOCKER-1: createTodo accepts blank titles and violates the service contract rule that titles must not be blank after trimming. +- BLOCKER-2: toggleTodo does not fail clearly for an unknown id. +Target files: +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +Acceptance rules: +- title must not be blank. +- createTodo trims title. +- toggleTodo fails clearly when the id is unknown. +- preserve required `@cpt-*` markers for the affected FEATURE IDs. +Do not add new features. +After writing, report changed files, validation commands, and remaining risks. +``` + +Codex prompt: + +```text +$cf-coding fix only the blocker findings from the Todo review. +Use the Todo FEATURE artifact as the governing implementation artifact, and check upstream DESIGN/DECOMPOSITION/PRD when a fix changes behavior or architecture. +Finding IDs/text: +- BLOCKER-1: createTodo accepts blank titles and violates the service contract rule that titles must not be blank after trimming. +- BLOCKER-2: toggleTodo does not fail clearly for an unknown id. +Target files: +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +Acceptance rules: +- title must not be blank. +- createTodo trims title. +- toggleTodo fails clearly when the id is unknown. +- preserve required `@cpt-*` markers for the affected FEATURE IDs. +Do not add new features. +After writing, report changed files, validation commands, and remaining risks. +``` + +Replace the example blocker text and file paths with your real findings, but keep the same tight structure. Do not fall back to vague placeholders such as "fix the blockers" or "update the needed files." + +Then validate again: + +```bash +npm test +npm run typecheck +cfs validate --local-only +``` + +Record the same evidence standard again: exact command, pass/fail, and key output excerpt or raw log reference. + +Then run a post-fix semantic review against the current code before handoff. + +Claude Code prompt: + +```text +/cf-coding review the current Todo code after the blocker fixes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. +Focus on whether the blockers are actually resolved, whether validation gaps remain, and whether any new scope creep was introduced. +Do not modify files. +``` + +Codex prompt: + +```text +$cf-coding review the current Todo code after the blocker fixes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. +Focus on whether the blockers are actually resolved, whether validation gaps remain, and whether any new scope creep was introduced. +Do not modify files. +``` + +Checkpoint: + +- The fix loop contains generation, validation, review, and human decision. + +### Lesson 6.2. Package The Review Evidence + +Create `docs/review-handoff.md`: + +```markdown +# Todo Review Handoff + +## Scope +State the bounded slice that was approved and what is intentionally out of scope. + +## Governing Artifact +Name the Todo FEATURE artifact as canonical for implementation. Also list upstream PRD, ADR, DESIGN, and DECOMPOSITION artifacts that govern this slice. Treat the brainstorm cache or wrap-up summary as original input evidence only. + +## Plan Lifecycle Artifacts +Link the `plan.toml`, relevant `brief-*` and `phase-*` files when they still exist, archived plan path when archived, or terminal cleanup receipt when lifecycle cleanup intentionally removed compiled files. + +## SDLC Traceability +| Layer | Artifact path | Key IDs or decisions | Validation evidence | +|---|---|---|---| +| PRD | | | | +| ADR | | | | +| DESIGN | | | | +| DECOMPOSITION | | | | +| FEATURE | | | | +| CODEBASE implementation + traceability | | | | + +## Changed Files +List the actual edited files only. + +## Validation +| Command | Scope | Pass/Fail/N/A | Output excerpt or raw log reference | Rerun after last blocker fix? | +|---|---|---|---|---| +| npm test | Todo API behavior | | | | +| npm run build | React UI build | | | | +| cfs validate --local-only | Studio local validation | | | | +| cfs validate | Workspace/cross-artifact validation status | | | | + +Add one row for every supported validation command you ran. If a command is unsupported, mark it `N/A` here and explain it again in `Unsupported Commands / N/A Rationale`. + +## Behavior Proof +| Flow | Steps or test | Expected result | Observed result | Evidence | +|---|---|---|---|---| +| List | | | | | +| Create | | | | | +| Toggle | | | | | +| Delete | | | | | + +## Unsupported Commands / N/A Rationale +| Command | Why unsupported or not applicable | Replacement evidence | +|---|---|---| +| | | | + +## Review Findings +- Blockers fixed: +- Non-blocking findings deferred: +- Findings still open: + +## Fixed +Map each fixed finding to the files or behavior it changed. + +## Deferred +Explain why each deferred item is safe to defer. + +## Remaining Risks +- Risk: +- Evidence: +- Why it is still open: + +## Gate And Approval Decisions +- Content approval: +- File-write approval: +- Accept/Fix/Defer decision: +- Reviewer gate decision: + +## Human Approval Needed +- Reviewer name or role: +- Exact approval requested: +- Risks this approval must cover: + +## Submission Status +Choose one: `passing` | `incomplete` | `not passing` +Reason: +``` + +Fill it from actual evidence. Do not invent green checks. + +Claude Code prompt: + +```text +/cf-write-docs review docs/review-handoff.md for missing evidence, hidden risk, and unclear human approval boundary. Do not modify files. +``` + +Codex prompt: + +```text +$cf-write-docs review docs/review-handoff.md for missing evidence, hidden risk, and unclear human approval boundary. Do not modify files. +``` + +Checkpoint: + +- A reviewer can read the handoff and decide what to do next. + +### Lesson 6.3. Core Path Complete Gate + +After Module 6, the core operator path is complete. + +Do not jump straight to the Capstone. The next modules turn the completed Todo slice into operational evidence: brownfield re-entry, workspace boundary awareness, teammate explanation, authoring extension, and governance. They are part of the required course path. + +## Module 7. Brownfield And Workspace Evidence + +### Lesson 7.1. Brownfield Retrofit + +Treat the completed Todo app as if another teammate handed it to you tomorrow. The goal is not to rebuild it; the goal is to prove you can re-enter an existing Constructor Studio project safely, detect conventions, and avoid blind reinitialization. + +Start with the brownfield gate, not with blind reinitialization. + +- Verify `.cf-studio/` exists and the host integrations you need are current. +- Do not rerun `cfs init` on a healthy initialized repo. +- Do not regenerate agents unless the relevant host files are missing or stale. +- Use `cf-auto-config` to inspect and refresh inferred repo-local rules only when the current session has not already verified them. + +In chat, activate Constructor Studio first: + +```text +Claude Code activation command: /cf +Codex activation command: $cf +``` + +For the course drill, treat the current Todo repo as brownfield even though you created it earlier in the course. That forces you to practice re-entry discipline. + +Before any product edit, inspect what was inferred and turn it into a safe brownfield plan: + +If the inferred rules are wrong, run one bounded generate pass to fix only the repo-local rule source before any future product edits. + +Claude Code prompt: + +```text +/cf-auto-config + +/cf-write-skills review the inferred project rules and call out anything that does not match how this Todo repo actually works. Do not modify files. + +/cf-explore summarize current Todo app conventions, architecture boundaries, test conventions, and risky areas. Do not modify files. + +/cf-plan create a safe brownfield re-entry plan for this already-initialized Todo repo before any future feature edits. +Constraints: +- phase 1 is inspection and convention alignment only; +- validate after each phase; +- surface human approval boundaries. +``` + +Codex prompt: + +```text +$cf-auto-config + +$cf-write-skills review the inferred project rules and call out anything that does not match how this Todo repo actually works. Do not modify files. + +$cf-explore summarize current Todo app conventions, architecture boundaries, test conventions, and risky areas. Do not modify files. + +$cf-plan create a safe brownfield re-entry plan for this already-initialized Todo repo before any future feature edits. +Constraints: +- phase 1 is inspection and convention alignment only; +- validate after each phase; +- surface human approval boundaries. +``` + +Expected result: + +- A convention summary. +- A short list of inferred-rule fixes or confirmations. +- A risk list. +- A brownfield re-entry plan before future edits. + +Checkpoint: + +- `docs/course-notes.md` records the current conventions, the brownfield re-entry plan path or fallback note, and the first safe brownfield phase. + +### Lesson 7.2. Multi-Repo Workspace + +Run a workspace boundary check even when the course repo is currently single-repo. The goal is to prove whether your evidence is local-only or workspace-aware, not to pretend you have multiple repos. + +Workspace model: + +- In the normal course repo, docs and code live together. Record that validation is local-repo evidence unless you configure an explicit workspace. +- In a split repo, use a parent directory such as `~/todo-workspace/` that contains the orchestration repo plus sibling repos like `todo-docs/` and `todo-app/`. +- Run workspace commands from the orchestration repo root that owns the workspace config. +- If you need to scan a broader parent directory while keeping the workspace config in the orchestration repo, stay in that orchestration repo root and pass both `--root` and `--output .cf-workspace.toml`. +- Current CLI/code uses `.cf-workspace.toml` as the canonical standalone filename. Some older Studio workflow docs still mention `.studio-workspace.toml`; treat that as a legacy alias only, and do not keep both files in the same repo. + +Workspace terminal flow when you intentionally configure split-repo evidence: + +```bash +cfs workspace-init --root ~/todo-workspace/ --output .cf-workspace.toml +cfs workspace-add --name docs --path ../todo-docs --role artifacts +cfs workspace-add --name app --path ../todo-app --role codebase +cfs workspace-info +# only when you added one or more Git URL sources with --url +cfs workspace-sync +cfs validate +``` + +Required inspection commands for the course: + +```bash +cfs where-defined --id cpt-todo-feature-todo-crud +cfs list-ids --source docs +cfs validate --local-only +cfs validate +cfs validate --source docs +cfs validate --source docs --local-only +cfs map --local-only +cfs map +``` + +Use `--source` when a workspace source named `docs` exists. If it does not exist, record that source-targeted validation is not available in this run and keep the `validate --local-only` versus `validate` comparison as your required evidence. `--local-only` controls whether validation stays local; `--source` controls which source is targeted. They are independent and can be combined. + +Claude Code prompt: + +```text +/cf-map show the local and workspace traceability edges that affect the Todo feature, and call out anything degraded or unresolved. Do not modify files. +``` + +Codex prompt: + +```text +$cf-map show the local and workspace traceability edges that affect the Todo feature, and call out anything degraded or unresolved. Do not modify files. +``` + +Expected result: + +- You know which repos are reachable and which are degraded. +- You know whether a source is a local path source or a Git URL source. +- You know that `workspace-sync` explicitly fetches or updates Git URL sources only; it does not update local path sources. +- You know whether validation and mapping are workspace-aware, local-only, source-targeted, or both source-targeted and local-only. +- You do not confuse workspace federation with project extensibility. + +Recovery: + +- If a source is unreachable, keep the evidence: `workspace-info` warnings, `workspace-sync` output, or the exact Git URL reachability failure. +- If `workspace-info` says a source is not cloned, do not guess; record the degraded state and run `workspace-sync` only for Git URL sources. +- Compare `cfs validate --local-only` with `cfs validate`, and compare `cfs map --local-only` with `cfs map`. +- Do not claim cross-repo health from local-only output. + +Checkpoint: + +- You have `workspace-info` output, one cross-repo evidence lookup, and one clear statement of what is local-only versus workspace-aware. + +### Lesson 7.3. Failure And Large Input Recovery + +When a request is too large, do not keep adding text to the same chat. Use a smaller unit of work. + +Useful chat recovery. + +Claude Code prompt: + +```text +/cf-explore summarize this oversized Todo review input into the smallest safe review units, preserving exact filenames, findings, and follow-up questions. Do not modify files. +``` + +Codex prompt: + +```text +$cf-explore summarize this oversized Todo review input into the smallest safe review units, preserving exact filenames, findings, and follow-up questions. Do not modify files. +``` + +Recovery drill: + +| Problem | Recovery | +|---|---| +| Validation fails and the cause is unclear | Ask `cf-coding` to triage the failure and fix only the bounded blocker set. | +| `cfs validate --local-only` passes but workspace validation or CI fails | Compare `cfs validate --local-only` with `cfs validate`, compare `cfs map --local-only` with `cfs map`, and use `cf-map` if you need a read-only explanation of the degraded edges. | +| Review or validation mentions language/script issues | Use human review of the learner-facing copy plus the normal repo validation flow; if wording risk still matters, ask `cf-write-docs` to point out unclear passages without treating language review as a public `cfs` command. | +| Traceability shape is unclear | Optionally run `cfs map`, `cfs map --local-only`, or `cf-map` to see whether the missing edge is local or workspace-wide. | +| The host blocks writes because confirmation or safety gates were not satisfied | Give an explicit bounded write instruction, or restate `read-only` if this should be analysis only. If the host integration is stale, regenerate it and retry from repo root. | +| The host wrote during a review request | Stop, inspect the diff, revert only with human intent, then restart in a fresh read-only session. | + +Explain the recovery state when needed. + +Claude Code prompt: + +```text +/cf-explain explain why the Todo validation or review state failed, which evidence is local-only versus workspace-wide, and the safest next recovery step. Do not modify files. +``` + +Codex prompt: + +```text +$cf-explain explain why the Todo validation or review state failed, which evidence is local-only versus workspace-wide, and the safest next recovery step. Do not modify files. +``` + +Codex-safe checklist: + +- Restate `read-only` when you want analysis. +- Start a fresh session when switching from generation to review. +- Inspect diffs after every implementation pass before asking for the next change. +- If source-of-truth files changed, regenerate host integrations before trusting host surfaces again. +- Use `/clear` only when that host surface exposes it. + +Checkpoint: + +- You can recover from an oversized or polluted session without weakening the evidence chain. + +## Module 8. Explain, Onboard, And Teach The Project + +### Lesson 8.1. Interactive Explanation + +After the Todo project has code and evidence, ask Constructor Studio to explain it. + +Claude Code prompt: + +```text +/cf-explain explain the current Todo app architecture, evidence chain, and review status for a new teammate. Do not modify files. +``` + +Codex prompt: + +```text +$cf-explain explain the current Todo app architecture, evidence chain, and review status for a new teammate. Do not modify files. +``` + +Expected result: + +- A bounded explanation. +- No new product claims. +- Clear distinction between implemented behavior and pending review. + +Checkpoint: + +- Paste the explanation or a summary into `docs/course-notes.md`. + +### Lesson 8.2. Review-Ready Explain Package + +Keep Module 8 interactive by default. Use `cf-explain` when a teammate needs a live walkthrough or onboarding conversation. + +Use `cf-explain` (package mode) here only when the Todo project is already review-ready and you want to package existing evidence into durable docs. If you want to change how explain packaging works, or use explain-package authoring as an extension exercise, treat that as Module 9 bridge work instead of normal onboarding. + +Claude Code prompt: + +```text +/cf-explain build the explain handoff package for the Todo app. +Audience: teammate joining the project. +Scope: Todo SDLC artifact chain, implemented Todo backend/API slice, React UI slice, validation output, traceability evidence, and review handoff. +Do not invent behavior that is not in the repo. +``` + +Codex prompt: + +```text +$cf-explain build the explain handoff package for the Todo app. +Audience: teammate joining the project. +Scope: Todo SDLC artifact chain, implemented Todo backend/API slice, React UI slice, validation output, traceability evidence, and review handoff. +Do not invent behavior that is not in the repo. +``` + +Expected result: + +- A package under a generated path such as `.cf-studio/.cache/explain/packages/todo-handoff-2026-05-27T120000Z/`. +- An `index.md` entry point plus portion files that explain the project. +- Source-grounded claims only. + +Checkpoint: + +- Open `index.md` first, inspect one portion file for source links and invented claims, then decide whether the package is ready to share. + +## Module 9. Author And Extension Bridge + +This module is not required to finish the Todo app. Enter it only after three gates are true: + +- Your operator baseline is complete and you can run the normal plan/generate/analyze loop. +- You know which file is the editable source of truth for the behavior you want to change. +- The host integrations you plan to use have already been generated at least once. + +### Lesson 9.1. Editable Truth Versus Generated Surfaces + +Rule: + +- Edit repo-local configuration and source-of-truth files. +- Regenerate host integrations. +- Do not edit generated host surfaces as if they were product truth. +- After any repo-local rule, prompt, agent, manifest, or kit-source change, regenerate host integrations before using those host surfaces again. + +Concrete map: + +| If you want to change... | Edit this source of truth | Do not treat this as truth | +|---|---|---| +| Project settings or workspace registration | `.cf-studio/config/core.toml` or standalone `.cf-workspace.toml` / inline `[workspace]` | Generated host files that merely consume those settings | +| System and artifact registry | `.cf-studio/config/artifacts.toml` | `.cf-studio/.gen/*` or host-generated summaries | +| Repo-local prompts, workflows, rules, or agents | Repo `manifest.toml`, included manifests, and the source files they point to | Generated host surfaces such as `.codex/agents/*.toml`, repo host integration files, or other generated agent wrappers | +| Manifest-driven kit resources | The resource file itself plus its binding in `core.toml` when applicable | Copied/generated outputs that were assembled from those bindings | + +Host surfaces differ in file layout: + +- Claude Code integrations are generated under `.claude/skills/` and `.claude/agents/`. +- Codex/OpenAI integrations use shared `.agents/skills/` plus `.codex/agents/*.toml`. +- In both cases, regenerate the host integration after source-of-truth changes, then reopen or reload the host before trusting the generated surface. + +Checkpoint: + +- You can name the editable source and the generated surface for one project rule, and you know when regeneration is required. + +### Lesson 9.2. Choose The Extension Path First + +Before you change any Module 9 rule, choose how that rule is meant to run: + +| Path | Best for | Tradeoff | +|---|---|---| +| Native subagent path | Hosts with strong built-in subagent or skill execution | More host-specific behavior; less portable | +| Chat-only path | Portable repo-local prompts and bounded manual operator flow | More discipline required from the operator each time | +| Delegated `ralphex`-style path | Exported plans or isolated execution in another runner | Adds another execution boundary and another recovery surface | + +Checkpoint: + +- `docs/course-notes.md` names the chosen extension path and one reason it fits this Todo project. + +### Lesson 9.3. Review Prompt, Workflow, Or Agent Instructions + +Use the right review lens before rewriting behavior: + +- Use `cf-write-skills` when the target behaves like an instruction contract, state machine, menu, or workflow router (it runs the PDSL-aware prompt/workflow/skill review); use `cfs pdsl validate` for deterministic PDSL block validation. +- Use `cf-write-skills` semantic review when the main risk is ambiguity, weak UX, unsafe write behavior, or missing approval boundaries. +- Use a prompt bug-finding review when you suspect hidden failure modes, contradictory routing, unsafe recovery, or regressions outside the happy path. + +Use `cf-write-skills` when the target behaves like an instruction contract. + +Claude Code prompt: + +```text +/cf-write-skills review the project instruction or workflow file for state-machine correctness, unsafe defaults, missing stop points, and unclear user prompts. +``` + +Codex prompt: + +```text +$cf-write-skills review the project instruction or workflow file for state-machine correctness, unsafe defaults, missing stop points, and unclear user prompts. +``` + +For a normal semantic review. + +Claude Code prompt: + +```text +/cf-write-skills review this project instruction for ambiguity, missing contracts, interaction UX issues, and unsafe write behavior. Do not modify files. +``` + +Codex prompt: + +```text +$cf-write-skills review this project instruction for ambiguity, missing contracts, interaction UX issues, and unsafe write behavior. Do not modify files. +``` + +For a prompt bug-finding lens. + +Claude Code prompt: + +```text +/cf-write-skills review this project instruction for prompt bugs, hidden failure modes, contradictory routing, and unsafe recovery behavior. Do not modify files. +``` + +Codex prompt: + +```text +$cf-write-skills review this project instruction for prompt bugs, hidden failure modes, contradictory routing, and unsafe recovery behavior. Do not modify files. +``` + +Expected result: + +- A review memo, not an immediate rewrite. +- Clear distinction between prompt review and implementation. + +Checkpoint: + +- You can identify one ambiguity, one missing contract, and one human approval boundary. + +### Lesson 9.4. Turn Review Findings Into A Bounded Fix Prompt + +Do not jump from an instruction review straight into an open-ended rewrite. First convert the review into a bounded remediation handoff. + +Use this exercise after any prompt, workflow, or agent review. + +Claude Code prompt: + +```text +/cf-write-skills convert these approved prompt/workflow/agent review findings into a bounded remediation handoff. +Return: +- the exact finding IDs or quoted findings in scope; +- the exact source-of-truth files to edit; +- the approvals that must exist before writing; +- the validation or read-back steps required after the fix; +- a final `cf-coding` fix prompt that does not widen scope. +Do not modify files. +``` + +Codex prompt: + +```text +$cf-write-skills convert these approved prompt/workflow/agent review findings into a bounded remediation handoff. +Return: +- the exact finding IDs or quoted findings in scope; +- the exact source-of-truth files to edit; +- the approvals that must exist before writing; +- the validation or read-back steps required after the fix; +- a final `cf-coding` fix prompt that does not widen scope. +Do not modify files. +``` + +Checkpoint: + +- You can turn review findings into a fix prompt that names exact files, exact findings, and exact post-fix checks. + +### Lesson 9.5. Add One Bounded Project Rule + +Example rule: + +```markdown +# Todo Project Rule + +Every public Todo operation must have at least one validation or test note in the review handoff. +``` + +Claude Code prompt: + +```text +/cf-write-skills add a small project-local rule for Todo review evidence. +Scope: +- rule only; +- no product behavior change; +- after writing, explain which source files changed and which host integrations must be regenerated. +``` + +Codex prompt: + +```text +$cf-write-skills add a small project-local rule for Todo review evidence. +Scope: +- rule only; +- no product behavior change; +- after writing, explain which source files changed and which host integrations must be regenerated. +``` + +Then regenerate the host you use: + +```bash +cfs generate-agents --agent claude +# or +cfs generate-agents --agent openai +``` + +Checkpoint: + +- You made one M9 extension that governs the project without changing Todo behavior. + +## Module 10. Governance And Team Adoption + +### Lesson 10.1. The Team Operating Rule + +Team rule: + +```text +No Todo feature is accepted until the governing artifact, changed files, validation output, semantic review, and human approval boundary are visible. +``` + +Host rule: + +```text +Use the host-specific prompt card for the host you are running. Do not mix `/cf` and `$cf` in the same copied prompt. If a host surface looks stale, regenerate that host integration and rerun the relevant gate. +``` + +Plain meaning of human approval: + +- A named reviewer or reviewer role makes a decision such as "approve for merge," "approve with listed deferrals," or "request changes." +- Record that decision in `docs/review-handoff.md`. +- Also record the open risks that reviewer is accepting, rejecting, or sending back. + +Checkpoint: + +- Your team rule names the evidence and the host difference. + +### Lesson 10.2. CI And Validation + +If your project has CI, map local commands to CI checks. + +Example: + +```markdown +| Evidence | Local command | CI check | +|---|---|---| +| TypeScript | npm run typecheck | typecheck | +| Tests | npm test | test | +| Studio validation | cfs validate --local-only | constructor-studio-validate | +``` + +Pinned-install discipline: + +- This course is pinned to Constructor Studio `1.0.0`. +- If your local install or generated host files drift from the `1.0.0` course source, stop the run and reconcile before continuing. +- Reinstall the pinned `1.0.0` CLI from the same approved source you used in setup, regenerate the host integrations you actually use, and rerun validation. +- Do not treat Claude/Codex host surfaces as self-updating. Generated agent or prompt files stay stale until you regenerate and reload them. + +Local-only versus workspace-aware validation: + +| Command | Use it when | What it proves | What it does not prove | Example | +|---|---|---|---|---| +| `cfs validate --local-only` | You need a repo-local check, or workspace sources are missing or unreachable. | The current repo passes deterministic Studio checks using only local state. | It does not prove cross-repo reachability, workspace linkage, semantic correctness, or human approval. | Your app repo validates locally while the docs repo is offline. | +| `cfs validate` | The repo is workspace-aware and the needed sources are reachable. | The local repo and workspace-linked sources can be checked together under the current workspace config. | It still does not prove semantic correctness, product quality, or acceptance approval. | Docs and app repos both resolve, and cross-repo evidence can be checked before handoff. | + +Remember: + +- Local validation is not semantic review. +- Workspace-aware validation is stronger than local-only validation, but it is still not semantic review. +- CI passing is not human approval. +- Human review of learner-facing language stays outside the core Todo command canon. Use normal repo validation plus explicit reviewer judgement for wording quality. + +### Lesson 10.3. Source-Truth Reconciliation Before Teaching Or Reuse + +If you will teach, reuse, or adapt this course after the core Todo path, perform one explicit reconciliation pass against current source truth first. + +Minimum deliverables: + +- conflict table; +- approved phrasing list; +- exclusions or deferrals; +- reconciled routing/control-plane notes; +- version note confirming whether `1.0.0` still matches the real source you inspected. + +Do not skip this because the draft "looks close enough." The learner-facing copy stays trustworthy only when the command canon and control-plane notes were explicitly reconciled. + +Checkpoint: + +- `docs/course-notes.md` includes one comparison row for `cfs validate --local-only` versus `cfs validate` and one sentence about what neither command proves. + +### Lesson 10.4. Reference-Only Admin And Migration Topics + +Some capabilities are real but not part of the core Todo path. + +Reference-only means: + +- Learn the term and when it applies. +- Do not run it in the capstone or list it in the final package unless your repo already depends on it or the assessor explicitly asks for it. + +Reference-only examples: + +- `cfs mirror` overrides: advanced admin material. +- Language governance review: keep it as human review plus normal validator evidence, not as a required Todo command. +- Cypilot migration commands: caveat material, not core coursework. + +Cypilot migration caveat: + +- deterministic stage can use the current v1.0.0 migration command documented by Studio for Cypilot-era projects; +- SDLC/OpenSpec migration uses the kit workflow `cf-studio migrate-openspec`; treat migration as a phased, code-verified, special-case workflow, not a Todo app command; +- during OpenSpec migration, code is treated as the ultimate source of truth, legacy spec claims may be rewritten to match actual code, outputs are registered with `FULL` traceability, and each phase gate requires explicit user approval before continuing; +- `.cf-workspace.toml` may be involved; +- preserved `@cpt-*` markers need attention; +- regenerated host integrations are required when migration touches agent files. + +Treat migration as a special-case note, not as an ordinary Todo command canon item. + +Checkpoint: + +- You can mention migration without turning it into the Todo capstone. + +## Module 11. Capstone + +Context reset (optional): the capstone runs from the artifacts, plan, and code already on disk. Start it in a fresh chat to keep context lean — re-activate (`/cf`; on Codex also re-send `disable autonomous mode`) first. + +### Capstone Goal + +Produce a review-ready Todo package. + +Your final package must include: + +- brainstorm evidence: saved `.cf-studio/.cache/brainstorm/...` path when save mode was used, or the approved wrap-up summary recorded in `docs/course-notes.md`; +- SDLC artifact chain: PRD, ADR, DESIGN, DECOMPOSITION, and Todo FEATURE; +- `docs/course-notes.md`; +- the on-disk plan lifecycle evidence: active plan files, archived plan path, or terminal cleanup receipt as applicable; +- an explicit note for `briefs_only`, `prompts_emitted`, cleanup, or archive states when compiled phase files do not exist; +- TypeScript backend/API files, or a clear mapping to the existing architecture when that slice was already present; +- React UI files, or a clear mapping to the existing architecture when that slice was already present; +- validation output, including which commands passed, failed, or were not applicable; +- SDLC validation evidence, including artifact validation and code marker/coverage checks when available; +- behavior proof for list, create, toggle, and delete through targeted tests or a smoke checklist; +- semantic review findings; +- fixed findings; +- deferred findings with rationale; +- remaining risks; +- gate and approval decisions; +- `docs/review-handoff.md`; +- Module 7 brownfield/workspace evidence; +- Module 9 extension/governance note. + +### Capstone Steps + +1. Confirm setup. + +```bash +cfs --version +cfs info +cfs validate-kits --kit sdlc +cfs validate --local-only +cfs validate --artifact docs/todocourse/PRD.md +cfs validate --artifact docs/todocourse/ADR/cpt-todocourse-adr-todo-architecture.md +cfs validate --artifact docs/todocourse/DESIGN.md +cfs validate --artifact docs/todocourse/DECOMPOSITION.md +cfs validate --artifact docs/todocourse/features/todo-crud.md +``` + +Replace every sample artifact path with the actual registered files in your repo. + +If `cfs --version` does not resolve to `1.0.0`, stop and reconcile the install before continuing. + +If Studio or kit behavior looks stale, stop the capstone run, reinstall the pinned `1.0.0` source you used in setup, regenerate the host integrations you use, and rerun validation. Do not assume the host surface refreshed itself. + +2. Confirm the governing artifacts. + +Claude Code prompt: + +```text +/cf-sdlc-change-impact-analysis review the Todo SDLC artifact chain for unclear scope, missing acceptance evidence, broken references, and unsupported assumptions. Include the brainstorm cache path or approved wrap-up summary only as original input evidence. Do not modify files. +``` + +Codex prompt: + +```text +$cf-sdlc-change-impact-analysis review the Todo SDLC artifact chain for unclear scope, missing acceptance evidence, broken references, and unsupported assumptions. Include the brainstorm cache path or approved wrap-up summary only as original input evidence. Do not modify files. +``` + +If PRD, ADR, DESIGN, DECOMPOSITION, or FEATURE is missing, create or repair those artifacts before planning code. Do not implement from brainstorm output alone. + +3. Confirm or create the implementation plan. + +If a current plan already exists, inspect `plan.toml` read-only first. Cite `plan.execution_status`, `plan.lifecycle_status`, and each `phases[].status` entry from disk before you choose the next phase. + +If no current plan exists, or the current plan is stale after a scope or architecture change, use `cf-plan` to create or revise it. + +Create-plan prompt. + +Claude Code prompt: + +```text +/cf-plan create a Todo implementation plan with backend/API, React UI, validation, findings triage, and handoff phases. +Use the Todo FEATURE artifact as the governing implementation artifact and preserve SDLC `@cpt-*` traceability. +Do not implement yet. +``` + +Codex prompt: + +```text +$cf-plan create a Todo implementation plan with backend/API, React UI, validation, findings triage, and handoff phases. +Use the Todo FEATURE artifact as the governing implementation artifact and preserve SDLC `@cpt-*` traceability. +Do not implement yet. +``` + +Revise-plan prompt. + +Claude Code prompt: + +```text +/cf-plan revise the existing Todo implementation plan so it still has backend/API, React UI, validation, findings triage, and handoff phases. +Use the Todo FEATURE artifact as the governing implementation artifact and preserve SDLC `@cpt-*` traceability. +Do not implement yet. +``` + +Codex prompt: + +```text +$cf-plan revise the existing Todo implementation plan so it still has backend/API, React UI, validation, findings triage, and handoff phases. +Use the Todo FEATURE artifact as the governing implementation artifact and preserve SDLC `@cpt-*` traceability. +Do not implement yet. +``` + +The capstone package is not complete if you can only point to a plan idea in chat. Keep the plan lifecycle artifacts on disk, or record a justified fallback in `docs/review-handoff.md`. + +The plan response should report the created plan path. If it does not, recover it from the repo root: + +```bash +find .cf-studio/.plans -name plan.toml -exec ls -t {} + | head -n 1 +``` + +Before executing a phase in the capstone, cite the exact `phases[].status` entries from `plan.toml` in `docs/course-notes.md` and justify why the selected phase is next. +If your host offers guarded same-chat native execution for the selected compiled phase, use that. Otherwise use the new-chat startup prompt contract from Lesson 3.5 so the execution session reads `plan.toml`, resolves the phase from manifest state, updates status, and follows only the selected phase file. `cf-plan` is for plan creation or revision only. + +4. Implement or finish the backend/API slice. + +`cf-sdlc-implement` reports the target files, validation commands, write scope, FEATURE-sync scope, and traceability coverage before it writes; approve those exact paths. + +Claude Code prompt: + +```text +/cf-sdlc-implement implement or finish only the Todo TypeScript backend/API slice from the Todo FEATURE artifact. +Approved write scope: +- package.json, only to set scripts.dev:api to the real backend entrypoint after the API exists +- src/server/index.ts +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- npm test -- todoApi +- npm run build +- cfs validate --local-only +Report changed files and validation. +In FULL traceability mode, preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs. +Switch `scripts.dev:api` to the real API entrypoint, such as `tsx src/server/index.ts`, before smoke testing. +Update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap. +``` + +Codex prompt: + +```text +$cf-sdlc-implement implement or finish only the Todo TypeScript backend/API slice from the Todo FEATURE artifact. +Approved write scope: +- package.json, only to set scripts.dev:api to the real backend entrypoint after the API exists +- src/server/index.ts +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- npm test -- todoApi +- npm run build +- cfs validate --local-only +Report changed files and validation. +In FULL traceability mode, preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs. +Switch `scripts.dev:api` to the real API entrypoint, such as `tsx src/server/index.ts`, before smoke testing. +Update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap. +``` + +Replace the sample paths and commands with the exact paths the skill reports before sending the real prompt. + +5. Implement or finish the React UI slice. + +`cf-sdlc-implement` reports the target files, validation commands, write scope, FEATURE-sync scope, and traceability coverage before it writes; approve those exact paths. + +Claude Code prompt: + +```text +/cf-sdlc-implement implement or finish only the Todo React UI slice from the Todo FEATURE artifact. +Approved write scope: +- ui/src/App.tsx +- ui/src/components/TodoList.tsx +- ui/src/api.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- if a UI test harness exists: npm test -- TodoList +- if no UI test harness exists: npm run typecheck, npm run build, and the final smoke checklist +- npm run build +- cfs validate --local-only +Report changed files and validation. +In FULL traceability mode, preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs. +Update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap. +``` + +Codex prompt: + +```text +$cf-sdlc-implement implement or finish only the Todo React UI slice from the Todo FEATURE artifact. +Approved write scope: +- ui/src/App.tsx +- ui/src/components/TodoList.tsx +- ui/src/api.ts +- docs/todocourse/features/todo-crud.md, or the actual registered Todo FEATURE path, only for checkbox/status updates after tests pass +- docs/todocourse/DECOMPOSITION.md, or the actual registered DECOMPOSITION path, only for parent feature status update after every task-tracked FEATURE item is complete +Approved validation commands: +- if a UI test harness exists: npm test -- TodoList +- if no UI test harness exists: npm run typecheck, npm run build, and the final smoke checklist +- npm run build +- cfs validate --local-only +Report changed files and validation. +In FULL traceability mode, preserve scope markers and per-instruction `@cpt-begin` / `@cpt-end` block markers for implemented FEATURE IDs. +Update only the relevant FEATURE checkboxes/status after implementation and validation prove completion; otherwise leave them unchecked and record the gap. +``` + +Replace the sample paths and commands with the exact paths the skill reports before sending the real prompt. + +6. Finish Module 7 evidence before the final validation pass. + +- Document the brownfield re-entry mapping: current conventions, what changed during the course, and what must stay untouched in future edits. +- Capture workspace boundary evidence: `cfs workspace-info` when configured, one traceability lookup, and whether `cfs validate` is local-only or workspace-aware in this repo. + +7. Validate. + +```bash +npm test +npm run typecheck +npm run build +cfs validate --local-only +``` + +If the repo is workspace-aware and the required sources are reachable, also run: + +```bash +cfs validate +``` + +Also run SDLC/traceability checks through the host or CLI surfaces available in the repo: + +Claude Code prompt: + +```text +/cf-sdlc-implement validate code for the Todo FEATURE. Check `@cpt-*` marker references, missing implementations, orphan markers, and drift between code and FEATURE. Do not modify files. +``` + +Codex prompt: + +```text +$cf-sdlc-implement validate code for the Todo FEATURE. Check `@cpt-*` marker references, missing implementations, orphan markers, and drift between code and FEATURE. Do not modify files. +``` + +Run only commands your repo actually supports. `npm` is an example, not a law. If your repo uses `pnpm`, `yarn`, or direct package scripts, use the equivalent commands. For every unsupported command, record `N/A` and the reason in `docs/review-handoff.md`. + +Behavior proof is mandatory in the capstone. Use one of these: + +- targeted automated tests that explicitly prove list, create, toggle, and delete; or +- a manual smoke checklist with the exact steps, expected result, and observed result for list, create, toggle, and delete. + +If you cannot prove one of the four core behaviors, the capstone is not passing yet. + +8. Review. + +Claude Code prompt: + +```text +/cf-coding review the final Todo app changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. Focus on correctness, missing tests, scope creep, traceability gaps, validation gaps, review readiness, and remaining risk. Do not modify files. +``` + +Codex prompt: + +```text +$cf-coding review the final Todo app changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. Focus on correctness, missing tests, scope creep, traceability gaps, validation gaps, review readiness, and remaining risk. Do not modify files. +``` + +9. Fix blockers. + +Use the same tight blocker-fix template from Lesson 6.1. Example: + +Claude Code prompt: + +```text +/cf-coding fix only the blocker findings from the final Todo review. +Use the Todo FEATURE artifact as the governing implementation artifact. +Finding IDs/text: +- BLOCKER-1: createTodo accepts blank titles and violates the trimmed non-empty title rule. +- BLOCKER-2: toggleTodo does not fail clearly for an unknown id. +Target files: +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +Acceptance rules: +- title must not be blank. +- createTodo trims title. +- toggleTodo fails clearly when the id is unknown. +- preserve required `@cpt-*` markers for affected FEATURE IDs. +Do not add new features. +After writing, report changed files, validation commands, and remaining risk. +``` + +Codex prompt: + +```text +$cf-coding fix only the blocker findings from the final Todo review. +Use the Todo FEATURE artifact as the governing implementation artifact. +Finding IDs/text: +- BLOCKER-1: createTodo accepts blank titles and violates the trimmed non-empty title rule. +- BLOCKER-2: toggleTodo does not fail clearly for an unknown id. +Target files: +- src/server/todoApi.ts +- src/server/todoStore.ts +- tests/todoApi.test.ts +Acceptance rules: +- title must not be blank. +- createTodo trims title. +- toggleTodo fails clearly when the id is unknown. +- preserve required `@cpt-*` markers for affected FEATURE IDs. +Do not add new features. +After writing, report changed files, validation commands, and remaining risk. +``` + +After fixes, rerun the relevant validation commands and refresh the handoff evidence. A validation result from before the last fix does not close the loop. + +Rerun behavior proof after the last blocker fix: + +- If the blocker touched a core Todo flow, rerun the targeted tests for that flow or rerun the full list/create/toggle/delete smoke checklist. +- Replace stale behavior-proof entries in `docs/course-notes.md` and `docs/review-handoff.md`. +- If you cannot rerun the affected proof, mark the capstone `incomplete` or `not passing`. + +Then run the final post-fix semantic review. + +Claude Code prompt: + +```text +/cf-coding review the final Todo app after blocker fixes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. Confirm whether the blocker findings are resolved, whether behavior proof is fresh, whether validation and traceability evidence are fresh, and whether any new scope creep or risk appeared. Do not modify files. +``` + +Codex prompt: + +```text +$cf-coding review the final Todo app after blocker fixes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD. Confirm whether the blocker findings are resolved, whether behavior proof is fresh, whether validation and traceability evidence are fresh, and whether any new scope creep or risk appeared. Do not modify files. +``` + +`docs/review-handoff.md` must cite this post-fix review result before submission. + +Blockers are not deferrable in the capstone. Each blocker must be fixed and revalidated, or the submission must be marked incomplete or not passing. Only non-blocking findings may be deferred with rationale. + +10. Package. + +Fill `docs/review-handoff.md` with, at minimum: + +- governing artifact; +- SDLC artifact chain and traceability evidence; +- plan artifacts or justified fallback; +- `docs/course-notes.md` as the checkpoint evidence log; +- changed files; +- validation commands with pass/fail/`N/A`; +- behavior proof for list, create, toggle, and delete; +- unsupported commands with reason; +- review findings; +- fixed findings; +- deferred findings with rationale; +- remaining risks; +- gate or approval decisions already made; +- human approval needed: reviewer name or role, exact decision requested, and open risks that decision must cover. + +11. Optional author bridge. + +Claude Code prompt: + +```text +/cf-write-skills review one proposed project-local Todo rule or prompt improvement. Keep it as governance, not product behavior. +``` + +Codex prompt: + +```text +$cf-write-skills review one proposed project-local Todo rule or prompt improvement. Keep it as governance, not product behavior. +``` + +### Capstone Rubric + +| Area | Evidence required to pass | +|---|---| +| Source fidelity | `docs/review-handoff.md` names the governing artifact and uses repo-backed evidence only. | +| SDLC artifact chain | PRD, ADR, DESIGN, DECOMPOSITION, and FEATURE exist, validate or have justified non-blocking gaps, and the implementation follows FEATURE rather than the input brief alone. | +| Plan lifecycle | Active plan files, archived plan path, terminal cleanup receipt, or valid `briefs_only` / `prompts_emitted` evidence is present and matches `plan.toml`. | +| Scope control | Review output shows the Todo behavior stayed inside the Todo FEATURE and upstream SDLC artifacts, or any variance is explicitly approved through artifact updates first. | +| Backend/API evidence | The backend/API files are changed or explicitly mapped to the pre-existing architecture. | +| UI evidence | The React UI files are changed or explicitly mapped to the pre-existing architecture. | +| Behavior proof | There is explicit proof for list, create, toggle, and delete via targeted tests or a smoke checklist, and affected proof was rerun after the last blocker fix. | +| Validation discipline | Exact commands and outcomes are recorded per command, and the relevant commands were rerun after the last blocker fix. | +| Traceability discipline | Required `@cpt-*` markers are present or explicitly justified as not applicable, and marker/reference validation was run where available. | +| Review loop | Final post-fix semantic review findings exist, every blocker is fixed and revalidated, and only non-blocking findings are deferred with rationale. Any unfixed blocker means the capstone is incomplete or not passing. | +| M7 evidence | Brownfield re-entry and workspace boundary evidence are included. | +| Unsupported command handling | Every unsupported validation command is marked `N/A` with a reason in `docs/review-handoff.md`. | +| Dual-tool realism | Host differences are stated without claiming Claude/Codex parity. | +| Human approval | The reviewer role or person, requested decision, and open risks are plainly recorded. | + +Final checkpoint: + +- A human reviewer can understand what you built, how you validated it, what was reviewed, what remains risky, and whether the Todo app is ready to accept. + +## Final Assessment + +### Exact Submission Package + +Submit: + +- brainstorm evidence: saved `.cf-studio/.cache/brainstorm/...` path when save mode was used, or the approved wrap-up summary recorded in `docs/course-notes.md`; +- PRD, ADR, DESIGN, DECOMPOSITION, and Todo FEATURE artifacts; +- `docs/course-notes.md`; +- `docs/review-handoff.md`; +- active plan files, archived plan path, terminal cleanup receipt, or valid `briefs_only` / `prompts_emitted` evidence; +- the backend/API and React UI file set, or written architecture mappings for the slices that already existed; +- validation evidence for every supported command; +- SDLC validation and traceability evidence; +- behavior proof for list, create, toggle, and delete; +- submission status set to `passing`, `incomplete`, or `not passing` with a reason; +- final review findings plus fixed/deferred status; +- remaining risks and gate/approval decisions; +- Module 7 brownfield re-entry and workspace boundary evidence; +- Module 9 governance note. + +### Assessor Checklist + +- The governing FEATURE artifact exists and matches the implemented Todo behavior. +- The student can explain the boundary between PRD, ADR, DESIGN, DECOMPOSITION, FEATURE, and CODEBASE, using one concrete Todo example for each layer. +- Plan lifecycle evidence exists on disk, or the fallback is justified and credible. +- Validation commands are listed with pass/fail/`N/A`, and unsupported commands include reasons. +- Behavior proof exists for list, create, toggle, and delete. +- Claims about local-only versus workspace-aware validation match the commands actually run. +- The last blocker-fix step is followed by fresh validation evidence. +- Remaining risks and deferred findings are visible, not buried. +- No blocker is silently deferred. Any still-open blocker is marked as not passing or incomplete. +- Human approval is assigned to a person or role, with a concrete decision requested. + +Binary completion rule: + +- Complete only when every required package item exists and every evidence category has a concrete result, including local-only or workspace-aware status. +- If any required evidence item is missing, stale, or hand-waved, the capstone is incomplete. + +## Appendix A. Command Reference + +Use Appendix A while running the capstone, Appendix B when something goes wrong, and Appendix C when you need to explain where each capability fits in the course path. + +Required or common in most runs: + +```bash +cfs --version +cfs info +cfs validate-kits --kit sdlc +cfs validate --local-only +cfs validate --artifact docs/todocourse/PRD.md +cfs validate --artifact docs/todocourse/ADR/cpt-todocourse-adr-todo-architecture.md +cfs validate --artifact docs/todocourse/DESIGN.md +cfs validate --artifact docs/todocourse/DECOMPOSITION.md +cfs validate --artifact docs/todocourse/features/todo-crud.md +``` + +Claude Code quick prompts: + +```text +/cf +/cf-brainstorm brainstorm the PRD-level product requirements for the Todo app: actors, goals, functional requirements, non-goals, constraints, acceptance criteria, and product scope boundaries. Do not plan implementation yet +/cf-sdlc-doc-prd make PRD for the Todo app from the approved brainstorm wrap-up +/cf-sdlc-doc-adr make the ADR for the Todo app from the PRD +/cf-sdlc-doc-design make the DESIGN for the Todo app from the PRD and ADR +/cf-sdlc-decompose decompose the Todo DESIGN into ordered feature scope +/cf-sdlc-doc-feature make FEATURE for todo-crud from DECOMPOSITION and DESIGN +/cf-plan create a bounded implementation plan for the Todo FEATURE +/cf-sdlc-implement implement the approved Todo backend/API slice from the Todo FEATURE +/cf-sdlc-implement implement the approved Todo React UI slice from the Todo FEATURE +/cf-coding review the Todo changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD +/cf-sdlc-implement validate code for the Todo FEATURE +``` + +Codex quick prompts: + +```text +$cf +$cf-brainstorm brainstorm the PRD-level product requirements for the Todo app: actors, goals, functional requirements, non-goals, constraints, acceptance criteria, and product scope boundaries. Do not plan implementation yet +$cf-sdlc-doc-prd make PRD for the Todo app from the approved brainstorm wrap-up +$cf-sdlc-doc-adr make the ADR for the Todo app from the PRD +$cf-sdlc-doc-design make the DESIGN for the Todo app from the PRD and ADR +$cf-sdlc-decompose decompose the Todo DESIGN into ordered feature scope +$cf-sdlc-doc-feature make FEATURE for todo-crud from DECOMPOSITION and DESIGN +$cf-plan create a bounded implementation plan for the Todo FEATURE +$cf-sdlc-implement implement the approved Todo backend/API slice from the Todo FEATURE +$cf-sdlc-implement implement the approved Todo React UI slice from the Todo FEATURE +$cf-coding review the Todo changes against the Todo FEATURE, DESIGN, DECOMPOSITION, and PRD +$cf-sdlc-implement validate code for the Todo FEATURE +``` + +Workspace-aware checks: + +```bash +cfs validate +cfs map +``` + +Claude Code prompt: + +```text +/cf-auto-config +/cf-map explain local or workspace traceability edges for the Todo feature +``` + +Codex prompt: + +```text +$cf-auto-config +$cf-map explain local or workspace traceability edges for the Todo feature +``` + +Course setup bootstrap: + +```bash +cfs init +cfs kit install constructorfabric/studio-kit-sdlc +cfs info +cfs validate-kits --kit sdlc +cfs generate-agents --agent claude +cfs generate-agents --agent openai +``` + +During `cfs init`, accept the SDLC kit prompt if it appears. Use `cfs kit install constructorfabric/studio-kit-sdlc` if the kit was declined, skipped, missing, or not offered. `cfs validate-kits .` is useful as a broad kit-template check; `cfs validate-kits --kit sdlc` is the course's explicit SDLC-kit proof. + +Workspace boundary commands: + +```bash +cfs workspace-init --root ~/todo-workspace/ --output .cf-workspace.toml +cfs workspace-add --name docs --path ../todo-docs --role artifacts +cfs workspace-add --name app --path ../todo-app --role codebase +cfs workspace-info +cfs where-defined --id cpt-todo-feature-todo-crud +cfs list-ids --source docs +cfs validate --source docs +cfs validate --source docs --local-only +cfs map +``` + +Claude Code prompt: + +```text +/cf-brainstorm choose the smallest safe first Todo app slice +/cf-write-skills review docs/project-workflow.md +/cf-explain build the explain handoff package for the Todo app +``` + +Codex prompt: + +```text +$cf-brainstorm choose the smallest safe first Todo app slice +$cf-write-skills review docs/project-workflow.md +$cf-explain build the explain handoff package for the Todo app +``` + +## Appendix B. Troubleshooting + +| Problem | Recovery | +|---|---| +| `cfs` not found | Repair install or PATH, then retry `cfs --version`. | +| `.cf-studio/` created in wrong directory | Stop, move to repo root, reinitialize intentionally. | +| Host ignores activation | Regenerate host integrations, reopen or reload host, retry from repo root. In Claude Code use `/cf`; in Codex use `$cf`. | +| Host writes when asked to analyze | Stop, inspect the diff, open a fresh session, restate read-only scope, and rerun the host gate before continuing. | +| Write is blocked by approval or a safety gate | Narrow the requested file scope, confirm the write explicitly, and retry through the correct write-capable workflow instead of forcing it. | +| Plan is too broad | Ask `cf-plan` to review the plan, then revise with smaller phases. | +| Validation fails | Triage and fix only blockers with `cf-coding`. | +| Local commands pass but CI fails | Compare the exact CI job command, package manager, working directory, environment, and workspace reachability. Record the mismatch in `docs/review-handoff.md` before claiming parity. | +| Missing `npm` scripts | Use the repo's real package manager or equivalent script entry point (`pnpm`, `yarn`, task runner, or direct command). Mark unsupported examples as `N/A` with a reason. | +| Input is too large for one review | Ask `cf-explore` to summarize or split the input into smaller review or fix phases, then continue with the smallest safe unit. | +| Workspace source unreachable | Record degraded state, use `workspace-info`, compare with local-only validation. | +| Review context is polluted | Start a fresh session or use host-specific clear behavior where available. | + +Status cascade rule: + +- Update FEATURE task checkboxes only after the matching implementation, markers, and tests/behavior proof pass. +- Update `featstatus` only after every task-tracked FEATURE item in that feature is complete. +- Update the parent DECOMPOSITION feature entry only after the FEATURE is complete and validation confirms the status is consistent. +- Record before/after FEATURE and DECOMPOSITION states in `docs/course-notes.md`. + +## Appendix C. Module Map And Capability Summary + +This course keeps traceability visible without letting it swallow the operator path. + +Module map: + +- Module 1. Orientation: what Constructor Studio adds. +- Module 2. Setup for Claude Code and Codex. +- Module 3. Create the SDLC artifact chain and plan the Todo work. +- Module 4. Implement the TypeScript HTTP API slice. +- Module 5. Implement the React UI slice. +- Module 6. Fix loop and review discipline. +- Module 7. Brownfield and workspace scenarios. +- Module 8. Explain, onboard, and teach the project. +- Module 9. Author and extension bridge. +- Module 10. Governance and team adoption. +- Module 11. Capstone. + +Capability dispositions: + +- Core path after Module 6: SDLC kit installation, PRD, ADR, DESIGN, DECOMPOSITION, FEATURE, bounded planning, compiled phase execution, backend generation, UI generation, validation, review, blocker-fix loop, and evidence packaging. +- Branch material: brownfield retrofit, workspace federation, explain packaging, author extension, and team governance. +- Added into core learning: SDLC artifact pipeline, plan lifecycle, routing/control plane, safety gates, host strategy, validation discipline, review discipline, traceability markers, and evidence capture in `docs/course-notes.md`. +- Reference-only: `cfs mirror`, human language review notes, and Cypilot migration. +- Excluded as canon: bare `cf-` prompts as learner copy-paste examples. Course prompt cards use `/cf-` for Claude Code and `$cf-` for Codex. + +## Appendix D. Routing And Control-Plane Glossary + +Use this appendix when you need the under-the-hood states, not when you are simply trying to finish one bounded Todo phase. + +- The `cf` skill loads its core rules at session start (`SessionInit` emits a load report), then `IntentRouting` offers the matching `cf-*` skill; there is no separate pre-routing guard unit. +- Intent routing offers the most relevant `cf-*` skill (tagged `(suggested)` when your prompt carries an intent). +- Compound `find + fix` requests go to `cf-coding`, which finds and then fixes through its review-fix loop. +- The size gates are separate: + - raw input over about `500` lines hits the pre-routing overflow gate; + - analyze stays safest within about `2000` lines of single-context material; + - generate work estimated over about `2500` lines should escalate to `cf-plan`, which can decompose into smaller phases. +- `CF_PHASE_GATE` controls whether writes are allowed. +- `GIT_COMMIT_MODE` controls whether git actions may commit, stage, or do no git writes. +- `SUB_AGENTS_APPROVED` records whether native sub-agent execution was approved for the current chat session (with `SUB_AGENTS_INLINE` for the inline fallback). +- `INLINE_FALLBACK` is per workflow run; when `true`, the host falls back to inline or sequential execution instead of native sub-agent dispatch. diff --git a/courses/studio-overview.md b/courses/studio-overview.md new file mode 100644 index 0000000..b064bcc --- /dev/null +++ b/courses/studio-overview.md @@ -0,0 +1,199 @@ +# Constructor Studio v1 Overview Scripts for Video Production + + + +- [Production Framing](#production-framing) +- [Overview 1. Constructor Studio](#overview-1-constructor-studio) + - [Story Goal](#story-goal) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction) +- [Overview 2. Constructor Studio for CTO and R&D Leaders](#overview-2-constructor-studio-for-cto-and-rd-leaders) + - [Story Goal](#story-goal-1) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction-1) +- [Overview 3. Constructor Studio for Product Managers](#overview-3-constructor-studio-for-product-managers) + - [Story Goal](#story-goal-2) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction-2) +- [Overview 4. Constructor Studio for Architects](#overview-4-constructor-studio-for-architects) + - [Story Goal](#story-goal-3) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction-3) +- [Overview 5. Constructor Studio for DevLeads and Developers](#overview-5-constructor-studio-for-devleads-and-developers) + - [Story Goal](#story-goal-4) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction-4) +- [Overview 6. Constructor Studio for QA Engineers](#overview-6-constructor-studio-for-qa-engineers) + - [Story Goal](#story-goal-5) + - [Narrator Script and Visual Direction](#narrator-script-and-visual-direction-5) +- [Closing Note for Production Team](#closing-note-for-production-team) + + + +## Production Framing + +This document is a script pack for six 5-minute overview videos about Constructor Studio v1. Each video should feel like a simple story for a wide audience: first the problem, then the solution, then how the solution works. + +Use clear on-screen text throughout, not minimal text only. Let the narrator explain, and let text, subtitles, diagrams, and animation reinforce the same point so learners can hear and see the structure at the same time. + +Default story spine for every overview: + +1. Problem: AI tools now help teams generate much more code, markdown, specs, tasks, tests, and documentation. In mid-size and large organizations, the number of files and handoffs grows quickly. Existing tools can help generate even more, but they do not automatically give the organization control. +2. Solution: Constructor Studio is a customizable team environment for organizing AI-assisted software delivery across Product Managers, Architects, DevLeads, Developers, and QA engineers. +3. How it works: Studio routes work through shared workflows, file-backed evidence, role-specific skills, repeatable validation, and traceability between documents, code, and tests. + +Studio should be presented as covering the full software lifecycle: Plan, Build, and Operate. + +- Plan: intent, vision, discovery, strategy, definition. +- Build: architecture, construction, validation, release. +- Operate: operations, support, intelligence, optimization. +- Required on-screen lifecycle line or diagram in every overview: Intent -> Vision -> Discover -> Define -> Design -> Build -> Validate -> Release -> Operate -> Support -> Learn -> Evolve. + +Keep technical names late in the story. Start with the organizational pain, not with commands or internal mechanics. + +Learner-facing terms that can appear when needed: + +- `cfs` for terminal setup, validation, and project operations. +- `cf` for invoking Studio workflows in the AI coding tool. +- Concrete skills such as `cf-write-docs`, `cf-brainstorm`, `cf-explore`, `cf-explain`, `cf-sdlc-doc-prd`, `cf-sdlc-doc-design`, `cf-sdlc-doc-adr`, `cf-sdlc-implement`, `cf-sdlc-reverse-engineer`, `cf-sdlc-change-impact-analysis`, and `cf-coding`. + +Do not mention router-level workflow names in learner-facing video scripts. + +--- + +## Overview 1. Constructor Studio + +### Story Goal + +Explain why Constructor Studio was created, what goals it serves, and why teams and organizations need it beyond individual AI prompting. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | Modern AI tools give software teams a real productivity boost. They help write code, create markdown files, draft specs, generate tests, and explain unfamiliar systems much faster than before. | Show a team using AI tools. Code files, markdown docs, tasks, and tests appear rapidly around them. | AI makes more | +| 0:35-1:10 | But that boost creates a new problem. In a growing organization, the number of generated files and decisions can explode. Requirements drift. Design docs become stale. Tests stop matching intent. Code changes are hard to connect back to why they exist. | The generated files spread into disconnected clusters. Some links fade, some files conflict, some are marked incomplete. | More output, less control | +| 1:10-1:45 | Tools like OpenSpec and similar systems can help teams produce structured specs. That is useful. But generating more documents is not the same as keeping an organization aligned, consistent, and reviewable across teams. | Show a “generate specs” machine producing clean documents, then zoom out to messy handoffs between PM, architecture, development, and QA. | Generation is not governance | +| 1:45-2:20 | Constructor Studio was created for that organizational layer. Its goals are to keep AI-assisted delivery connected, reviewable, and adaptable across teams, so product work, architecture work, coding work, and QA work do not drift apart. | The scattered files move into one shared delivery map with role lanes and connecting lines. | Created for connected delivery | +| 2:20-3:05 | Studio is not only for one person writing better prompts. It is for collaboration between roles and between teams across the full software lifecycle. Product Managers shape requirements. Architects turn intent into decisions and design. Developers implement from approved context. QA checks behavior against traceable evidence. | PM, Architect, Developer, and QA lanes connect through shared files, then expand into lifecycle phases. | Teams across the lifecycle | +| 3:05-3:45 | The basic idea is simple: work is routed into the right workflow, with the right context, and with checks that make the result easier to inspect. Studio supports Plan, Build, and Operate as one delivery system: Intent -> Vision -> Discover -> Define -> Design -> Build -> Validate -> Release -> Operate -> Support -> Learn -> Evolve. | Scattered AI sessions across teams connect into a guided lifecycle path that spans planning, building, and operating. Keep the full lifecycle sequence visible on screen as a single line or clear diagram: Intent -> Vision -> Discover -> Define -> Design -> Build -> Validate -> Release -> Operate -> Support -> Learn -> Evolve. | Plan -> Build -> Operate; full lifecycle: Intent -> Vision -> Discover -> Define -> Design -> Build -> Validate -> Release -> Operate -> Support -> Learn -> Evolve | +| 3:45-4:25 | Studio works on top of the tools teams already like: Claude Code, GitHub Copilot, Cursor, and similar AI coding environments. It does not ask the organization to replace its technology stack just to get control over AI-assisted delivery. | Existing AI tools stay in place while Studio adds a workflow and evidence layer above them. | Keep your tools | +| 4:25-4:45 | Studio is also customizable. An organization can adapt templates, rules, workflows, validation, and codebase conventions instead of throwing away its existing process. The default SDLC kit gives teams a starting point they can adapt. | A default workflow adapts into several company-specific variants. | Fit your process | +| 4:45-5:00 | The outcome is control. AI can still help teams move faster, but the work becomes easier to connect, review, validate, and maintain. Constructor Studio turns AI-assisted output into a team delivery system. | End on a clean map where docs, code, tests, and review are connected. | Speed with control | + +--- + +## Overview 2. Constructor Studio for CTO and R&D Leaders + +### Story Goal + +Help technical leaders decide whether Constructor Studio is a useful organizational control layer for AI-assisted delivery. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | For CTOs and R&D leaders, the main AI question is no longer “can developers generate code faster?” They can. The harder question is what happens when many teams generate code, documents, tests, and decisions faster at the same time. | Multiple teams generate artifacts in parallel. The volume rises quickly. | Scale changes the problem | +| 0:35-1:10 | Without a shared operating model, speed can turn into fragmentation. Teams may use different templates, lose decision history, skip review evidence, or produce documents that no longer match the codebase. | Show separate team islands with inconsistent docs and unclear handoffs. | Fragmentation risk | +| 1:10-1:45 | Constructor Studio is a proposed solution for that layer. It is an open-source, customizable environment that helps organize collaboration across Product Managers, Architects, Developers, DevLeads, and QA engineers. | The islands connect into one shared operating layer. | Shared operating layer | +| 1:45-2:25 | Studio differs from individual or project-centered specification tools because it is focused on organizational delivery control. The goal is not just to create one more spec. The goal is to keep intent, decisions, implementation, tests, and review evidence connected. | Compare “project spec” with “organization workflow”: the second shows cross-role links. | Beyond project specs | +| 2:25-3:05 | The mechanism is straightforward. Studio uses workflows and concrete skills for different kinds of work: brainstorming, exploration, Product Requirements Documents, design documents, Architecture Decision Records, implementation, reverse engineering, and change impact analysis. | Show each role lane using the workflow that fits its job: product requirements, design, code, tests, and review. | Workflows by role | +| 3:05-3:40 | Traceability is the control point. CPT IDs can connect documents and code so teams can reason about consistency. Validation can check structure, references, and configured rules. Human review remains the final authority. | A chain connects Product Requirements Document, DESIGN, FEATURE, code, tests, and approval. | Traceable evidence | +| 3:40-4:20 | Adoption does not require a process, tech stack, or favorite tools reset. Teams can start with the default SDLC kit and then customize document templates, checklists, workflows, and codebase rules to match existing governance. | Default kit expands into organization-specific process gates and existing tool icons stay in place. | Start standard, adapt | +| 4:20-5:00 | The leadership case is simple: Constructor Studio helps preserve the AI productivity boost while reducing the risk that generated code and documents become inconsistent, incomplete, or impossible to govern at scale. | End with a leader dashboard-style view of connected teams and artifacts. | AI speed, governed delivery | + +--- + +## Overview 3. Constructor Studio for Product Managers + +### Story Goal + +Show Product Managers how Studio helps keep product intent clear, reviewable, and reusable downstream. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | Product work often starts as a conversation: a customer need, a stakeholder request, a feature idea, or a rough market assumption. AI can turn that into text very quickly. | A rough idea becomes a long generated document. | Ideas become text | +| 0:35-1:10 | The problem is that fast text can still be unclear. It may miss actors, constraints, edge cases, success criteria, or tradeoffs. When that unclear intent moves downstream, architects and developers fill gaps with assumptions. | Missing requirement fields create warning marks in later role lanes. | Fast text can drift | +| 1:10-1:45 | Constructor Studio helps Product Managers turn early intent into product requirements that are easier for the whole team to review and reuse. | Rough notes become a structured Product Requirements Document connected to architecture and QA. | Intent becomes reviewable | +| 1:45-2:25 | A PM can use `cf-brainstorm` to explore options before committing to scope. The point is not to get a pretty answer. The point is to surface alternatives, risks, missing questions, and decision criteria early. | Branching options appear, then collapse into a chosen direction with open questions. | Explore before scope | +| 2:25-3:05 | When the direction is ready, the Product Requirements Document workflow helps create or review requirements using structured expectations. `cf-write-docs` supports broader product writing when the document is less formal. | Two paths: formal Product Requirements Document and flexible product document. | Requirements and docs | +| 3:05-3:40 | Studio also helps with review and traceability. Requirements, and even specific paragraphs inside them, can use stable IDs that link to requirements defined elsewhere. That creates a graph of connected requirements that shapes the final product scope. | Requirement paragraphs receive stable IDs, then connect into a visible requirement graph. | Linked requirements | +| 3:40-4:25 | This improves collaboration because downstream teams receive something more stable than a chat transcript or an unstructured requirements document. Architects can see which requirements are covered by design, developers can see how they can be implemented, and QA can design tests against visible intent. | One Product Requirements Document feeds architecture, implementation, and QA lanes with trace links. | Stable handoff | +| 4:25-5:00 | Product Managers can also use phase tags to group requirement stories by delivery phase. Architects can see both the current scope and upcoming functionality, while development teams stay focused on the current delivery scope. When requirements move, Studio helps identify design or code that may need updates and gaps that need review. | End with requirement IDs grouped by phase, with changed items highlighting affected design and code nodes. | Intent that survives | + +--- + +## Overview 4. Constructor Studio for Architects + +### Story Goal + +Show Architects how Studio helps turn requirements and existing codebase context into controlled design decisions. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | Architects often sit in the middle of the AI acceleration problem. Product intent is changing faster. Code is changing faster. Documentation is being generated faster. But architecture still needs coherence. | Product docs, code changes, and design notes move quickly around an architect. | Speed needs coherence | +| 0:35-1:10 | The risk is hidden drift. A Product Requirements Document may imply one architecture. Existing code may support another. A design document may become stale as implementation moves ahead. | Show Product Requirements Document, design, and code slowly separating from each other. | Hidden drift | +| 1:10-1:45 | Architecture is usually a tradeoff between business requirements, technical constraints, future extensibility, operational costs, security, and performance. Architects need many inputs in view before they can make the right decision. | Inputs from requirements, code, operations, security, and performance converge into one decision view. | Many inputs, one decision | +| 1:45-2:25 | Constructor Studio helps keep those inputs accessible. `cf-explore` can gather relevant requirements, existing design material, codebase context, and previous decisions before the architect writes or changes a design. | Repository and document sources are scanned, then summarized into an architecture context map. | Explore first | +| 2:25-3:05 | When the decision is still open, `cf-brainstorm` helps compare options and tradeoffs. Studio then supports consistent, well-informed decisions with architecture document templates, validation rules, reviewable structure, and links back to the source requirements. | Options are compared against requirement, cost, security, and performance criteria. | Tradeoffs made visible | +| 3:05-3:45 | Studio follows modern architecture documentation practice by separating design documents from Architecture Decision Records. Design documents define how the system should work. Architecture Decision Records capture why specific decisions were made and what consequences they create. | DESIGN and Architecture Decision Record streams split, then link back to the same requirement. | Design and rationale | +| 3:45-4:25 | That separation also helps AI work with a cleaner context. Code generation can focus on the pure design content needed for implementation, while architectural history and rationale remain linked as evidence without always entering the generation context. | The code-generation context receives DESIGN; linked Architecture Decision Records stay available as rationale. | Smaller AI context | +| 4:25-5:00 | In existing systems, Architects can use `cf-sdlc-reverse-engineer` to reconstruct design understanding from code and `cf-sdlc-change-impact-analysis` to estimate what a proposed change may touch across documents, components, and repositories. The result is faster collaboration with fewer invisible architecture gaps. | Brownfield code turns into a design map with cross-repository impact links. | Fewer invisible gaps | + +--- + +## Overview 5. Constructor Studio for DevLeads and Developers + +### Story Goal + +Show DevLeads and Developers how Studio keeps implementation work bounded, traceable, and easier to review. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | Developers feel the AI boost directly. Code can be generated faster. Tests can be drafted faster. Bug explanations can arrive faster. But faster editing can also create faster confusion. | Code, tests, and fixes appear quickly in an editor. Some lose links to requirements. | Faster code, faster confusion | +| 0:35-1:10 | The problem is not that AI writes code. The problem is code without enough context: unclear requirement links, missing design decisions, weak tests, or changes that reviewers cannot trace back to intent. | A pull request appears with unanswered questions around it. | Context is the bottleneck | +| 1:10-1:45 | Constructor Studio helps developers start from approved inputs instead of an isolated AI answer or a loose ticket note. Work can begin from Product Requirements Document, design, Architecture Decision Record, or feature artifacts that explain why the change exists. | Editor opens next to linked FEATURE and DESIGN files. | Code from intent | +| 1:45-2:25 | For planned feature work, `cf-sdlc-implement` helps implement from approved FEATURE context. For smaller focused changes, `cf-coding` supports code and unit test work without pretending every edit needs a large process. | A large feature uses full workflow; a small fix uses a lighter path. | Right size workflow | +| 2:25-3:05 | For unfamiliar code or bugs, `cf-explore` helps developers understand the area before changing it. That matters because random edits in unknown code create review risk and regression risk. | A bug report links to targeted code exploration before the fix. | Explore before fixing | +| 3:05-3:45 | Tests become part of the same story. Instead of writing tests only against implementation details, developers can connect tests back to feature intent and expected behavior. | FEATURE intent generates code and tests side by side. | Tests follow intent | +| 3:45-4:25 | Before review, `cfs` can run repeatable checks for the configured project surface. These checks do not replace human judgment, but they give reviewers a cleaner evidence packet. | Terminal checks pass, then a reviewer inspects the linked evidence. | Checks before review | +| 4:25-5:00 | For DevLeads, the value is consistency across a team and across repositories. Workspaces can bring related specifications, libraries, API contracts, backend services, frontends, and mobile apps into one traceability view, so teams can spot gaps between requirements and real implementation. | Multiple repositories converge into one reviewable map with requirement, code, and test links. | Reviewable team work | + +--- + +## Overview 6. Constructor Studio for QA Engineers + +### Story Goal + +Show QA engineers how Studio makes expected behavior, evidence, and traceability easier to inspect before test work begins. + +### Narrator Script and Visual Direction + +| Time | Narrator Script | Animation / Visual Direction | On-Screen Text | +|---|---|---|---| +| 0:00-0:35 | QA teams are also affected by AI acceleration. More code changes arrive. More generated tests appear. More documents claim to describe behavior. But QA still needs to know what is actually expected. | A QA board receives many code, doc, and test artifacts at once. | More artifacts to verify | +| 0:35-1:10 | The problem is weak evidence. If requirements, design, implementation, and tests are disconnected, QA has to reconstruct intent from tickets, chats, diffs, and meetings. | A QA engineer follows broken links between ticket, doc, code, and test. | Intent gets scattered | +| 1:10-1:45 | Constructor Studio helps QA work from a clearer chain. A change can carry product intent, design context, feature behavior, implementation evidence, and validation results together. | The scattered artifacts connect into one evidence chain. | Clearer evidence chain | +| 1:45-2:25 | `cf-explore` and `cf-explain` help QA engineers understand the codebase and related documents before writing or extending tests. This is especially useful in brownfield systems where behavior is spread across older modules. | QA starts from a context map before writing tests. | Understand before testing | +| 2:25-3:05 | `cf-coding` can support automated test authoring when the expected behavior is clear. The goal is not to generate tests blindly, but to write tests against visible intent and requirement links. | Test cases connect back to feature behavior and requirements. | Test against intent | +| 3:05-3:45 | Repeatable checks add another signal. If references, structure, or configured traceability fail, QA can see that early. Passing checks do not prove quality, but failing checks expose review risk. | Validator catches a broken reference before QA approval. | Checks expose risk | +| 3:45-4:25 | This changes collaboration. QA is no longer only at the end of a code diff. QA can inspect the same delivery chain that Product, Architecture, and Development used to create the change. | QA joins the shared PM, Architect, Developer workflow map. | QA inside the flow | +| 4:25-5:00 | For QA engineers, Constructor Studio provides better context before testing, stronger evidence during review, and a clearer path from requirements to behavior and automated tests. QA can review where a requirement is tested: unit tests, integration tests, end-to-end tests, security tests, performance tests, and gaps that still need coverage. | End on requirement, feature, code, test layers, and approval connected across a workspace. | Better context, better tests | + +--- + +## Closing Note for Production Team + +Each overview must lead with the organizational problem before naming Studio mechanics. The audience should first feel the pain: AI creates more code and markdown faster, and that creates control, consistency, completeness, and review problems. + +Only after that should the narrator introduce Constructor Studio as the solution: a customizable collaboration environment for teams, roles, workflows, evidence, validation, and traceability. + +Production should use narration, on-screen text, subtitles, and simple diagrams together. Do not rely on voice alone when a phase model, evidence chain, or role handoff can be shown visually. + +Recurring visual pattern: + +- First show artifact explosion. +- Then show drift and inconsistency. +- Then show Studio connecting roles and artifacts. +- Then show a simple evidence chain from intent to code to tests to review.