Status: Active

Convention: 🖥 = run in a terminal. 💬 = paste into your artificial intelligence (AI) coding tool chat.

1. What It Is

Constructor Studio is an organizational workflow layer for AI-assisted software delivery. A workflow is a repeatable work process with known inputs, steps, checks, and outputs.

Align cross-functional delivery. It is built for companies where software work crosses many expert groups: product managers, architects, development teams, quality assurance (QA), performance engineering, development and operations (DevOps), security, delivery coordination office (DCO), platform teams, and reviewers who each read different parts of the same system. The main bottleneck is usually not raw code writing. It is keeping people, documents, code, decisions, tests, and operational constraints aligned while the work moves between teams.

Keep AI process-backed. Constructor Studio helps an organization put AI into its existing delivery process instead of replacing that process with unstructured chat. It gives teams repository-backed artifacts, templates, skills, checklists, deterministic validation rules, and traceability through Canonical Provenance Trace IDs (CPT IDs). Traceability means you can follow a requirement, decision, or task through later documents, code, tests, and reviews. An artifact is a reviewable project document such as a requirement, design, decision record, feature specification, or plan. Deterministic validation means the same files and rules produce the same check result. A CPT ID can connect a requirement to a design decision, a feature specification, implementation code, tests, and review evidence.

Separate focused AI roles. Constructor Studio is sub-agent driven where the AI coding tool supports sub-agents. It separates work into focused roles such as context discovery, planning, writing, review, and validation, so one long chat does not have to hold every responsibility at once. Sub-agent dispatch is user-gated: you can approve a dispatch, run work inline when supported, or stop before the role runs.

Make collaboration inspectable. The core idea is simple: make collaboration inspectable. Product Requirements Documents (PRDs), Architecture Decision Records (ADRs), DESIGN documents, decompositions, FEATURE specifications, code markers, checklists, and validation outputs can all become part of one connected set of files and checks. Different experts can review the part they own, while cfs checks structure, links, required sections, and configured consistency rules.

Package team delivery rules. Constructor Studio is also customizable. Teams can change document templates, artifact formats, review checklists, deterministic rules, skill behavior, and skill selection rules. Organizations can package those decisions into kits. A kit is an installable bundle of skills, templates, validation checklists, process instructions, and rules, so one team can standardize a delivery model and scale it across many repositories.

Details:

• Usage guide - workflow selection, first moves, skill message examples, delegation, workspaces, dependency map, and common mistakes
• Configuration guide - CPT IDs, artifacts, templates, checklists, deterministic validation, kits, dependency map, mirrors, and quick references
• Agent tools guide - how Constructor Studio maps into Claude Code, Cursor, Codex, Copilot, Windsurf, and other AI coding tools
• Project extensibility guide - organization-level composition, multi-repository patterns, configuration manifests, and extensibility

2. Install and Connect a Repository

🖥 Install the command-line interface (CLI):

pipx install git+https://github.com/constructorfabric/studio.git

🖥 Check that the install works:

cfs --version

🖥 Go to the repository you want to connect:

cd path/to/your/repository

🖥 Set up Studio there:

cfs init

When cfs init offers to install the Software Development Life Cycle (SDLC) kit, accept it. The SDLC kit is the usual starting point for product-to-code traceability.

🖥 Generate integration files for your AI coding tool:

cfs generate-agents

cfs init creates the repository-local Studio setup directory, normally .cf-studio/. The repository footprint is intentionally small: generated Studio runtime files, the local cfs support files, and generated AI coding tool agent configuration files are gitignored by default. cfs generate-agents writes or refreshes those tool integration files when needed, and they can be repaired or regenerated. Project configuration, project rules under config/rules/, and any kit content you choose to track are the parts your organization reviews and evolves.

If a repository already contains Constructor Studio setup files, you can usually skip the install and initialization steps. Open that repository in your AI coding tool and activate Studio in chat:

💬 Activate Studio:

cf

Then start with a concrete skill, for example:

💬 Open help:

cf-help

💬 Explore the repository:

cf-explore: find the main artifacts and code paths for the billing workflow

💬 Work on code:

cf-coding: implement the next safe phase of this migration

Install kits manually when you skipped the SDLC kit during cfs init, need to add it later, or want another predefined delivery model:

🖥 Install the SDLC kit:

cfs kit install constructorfabric/studio-kit-sdlc

🖥 Regenerate integration files after installing a kit:

cfs generate-agents

Other kit installation options exist for different organizational needs:

🖥 Install a kit from GitHub:

cfs kit install <owner/repo[@ref]>

🖥 Install a kit from a generic Git source:

cfs kit install git/<url>[//<subdir>][@<kit>] --version <ref>

🖥 Copy a local kit into the setup directory:

cfs kit install --path <path> --install-mode copy

🖥 Register a local kit in place:

cfs kit install --path <path> --install-mode register

Use a GitHub or generic Git kit when a platform or architecture team publishes a shared standard. Use copy when you want the kit resources copied into the setup directory. Use register when the kit source should stay in place inside the project or workspace.

Run validation locally and in continuous integration (CI):

🖥 Validate configured artifacts and traceability:

cfs validate

🖥 Validate guide tables of contents:

cfs validate-toc guides/USAGE-GUIDE.md guides/CONFIGURATION.md guides/AGENT-TOOLS.md

🖥 Check allowed document languages:

cfs check-language README.md guides/USAGE-GUIDE.md guides/CONFIGURATION.md guides/AGENT-TOOLS.md

More setup detail:

• Installation and setup reference
• Kit management
• AI-tool-specific setup and tradeoffs
• Mirror overrides
• Contributing

3. Success Story

A typical organization starts by installing the SDLC kit in the repository that owns delivery artifacts. If the organization works across several repositories, a lead or architect can set up a workspace: one repository for product and architecture documents, one for the user interface, one for backend services, and more for microservices or shared libraries.

The product manager starts with discovery and brainstorming:

💬 Gather context:

cf-explore: gather existing product notes, customer constraints, and related artifacts

💬 Explore options:

cf-brainstorm: map the options for the new billing workflow

💬 Write the product requirements:

cf-sdlc-doc-prd: write the Product Requirements Document for the billing workflow

The Product Requirements Document is reviewed against the configured methodology and checklist. Review findings are shown before fixes are applied, and the user approves the fix scope. Deterministic validation checks the artifact shape, required sections, references, and CPT ID structure:

🖥 Validate the repository:

cfs validate

The architect reads the Product Requirements Document, records technical decisions, and writes the design:

💬 Record a technical decision:

cf-sdlc-doc-adr: record the architecture decision for payment provider isolation

💬 Write the design:

cf-sdlc-doc-design: write the DESIGN document from the approved Product Requirements Document and Architecture Decision Records

💬 Decompose the design into features:

cf-sdlc-decompose: decompose the DESIGN document into reviewable FEATURE work

Development teams then implement scoped features. The implementation preserves CPT traceability in code and tests, so reviewers can see which code implements which approved requirement or design element:

💬 Write a feature specification:

cf-sdlc-doc-feature: write the FEATURE spec for invoice retry handling

💬 Implement the feature:

cf-sdlc-implement: implement the approved FEATURE specification with CPT markers and unit tests

💬 Review the code:

cf-coding: review the changed code for correctness, regression risk, and missing tests

Quality assurance, performance, security, DevOps, and delivery coordination teams use the same connected files and checks. They can review artifacts, create focused test plans, inspect deployment constraints, check operational risks, and validate whether the implementation still matches approved scope. They do not need to read the same document in the same way; each team can use the skill and checklist that matches its responsibility.

Concrete workflows may pause for shared gates before the main work starts: session interaction mode selection (assistant, normal, or debug), companion workflow selection, optional context discovery with cf-explore, optional structured brainstorming, plan-first for multi-step work, and sub-agent dispatch approval. Assistant mode acts like a visible guide in chat: it explains where the workflow is, why the current step is happening, what each option does next, and which path is recommended. Debug mode reuses cf-debug-prompts in a lighter run mode so tracing and breakpoints stay active while pauses happen only on breakpoints, WAIT/menu, or errors until you switch back to step mode. These gates keep discovery, planning, writing, review, and validation inspectable instead of hiding them inside one prompt.

Architects and leads can render a dependency map across documents and code:

🖥 Render the dependency map:

cfs map

💬 Review the map for broken references:

cf-map: find dangling references

💬 Inspect one feature's links:

cf-map: show which artifacts and code markers connect to the billing retry FEATURE specification

The result is not "AI wrote the project." The result is a reviewable delivery system: Product Requirements Document to Architecture Decision Record to DESIGN document to DECOMPOSITION document to FEATURE specification to code to tests, linked by CPT IDs, customizable by kit, and usable by the different teams that already own the software process.

Skills and Workflows

Base Constructor Studio skills:

Skill	Use
cf-help	See what Constructor Studio can do and where to start.
cf-explore: ...	Find relevant files, artifacts, rules, and project context.
cf-brainstorm: ...	Explore options before scope is fixed.
cf-auto-config	Infer or refresh project rules and setup for an existing repository.
cf-plan: ...	Split large or risky work into reviewable phases.
cf-coding: ...	Write, refactor, fix, or review source code.
cf-write-docs: ...	Write, revise, or review guides, reports, and README files.
cf-write-skills: ...	Write or review skills, prompts, workflows, and agent instructions.
cf-explain: ...	Walk through a document, pull request, code area, or decision.
cf-map: ...	Render or inspect the dependency map across documents and code.
cf-workspace: ...	Configure or work across multiple repositories.
cf-kit: ...	Create, validate, or update kit configuration.
cf-debug-prompts: ...	Debug skill or workflow behavior live, either in full step mode or via the lighter session run-mode gate.
cf-brave-new-world	Let Studio choose safe, reversible workflow defaults during a session.

cf-analyze and cf-generate are stable router entrypoints. They preserve the legacy verbs, resolve the best matching cf-* skill or companion group for the request, and pass the intent through; they are not the concrete analysis or generation workers themselves.

Software Development Life Cycle (SDLC) kit skills from constructorfabric/studio-kit-sdlc:

Skill	Use
cf-sdlc-doc-prd: ...	Write or revise a Product Requirements Document.
cf-sdlc-doc-adr: ...	Record an Architecture Decision Record.
cf-sdlc-doc-design: ...	Write or revise a DESIGN document.
cf-sdlc-decompose: ...	Break a design into ordered feature work.
cf-sdlc-doc-feature: ...	Write or revise a FEATURE specification.
cf-sdlc-implement: ...	Implement an approved FEATURE in code with traceability.
cf-sdlc-change-impact-analysis: ...	Analyze downstream impact from changed artifacts or code.
cf-sdlc-reverse-engineer: ...	Reconstruct SDLC artifacts from existing code and markers.
cf-sdlc-migrate-openspec: ...	Convert OpenSpec material into Constructor Studio SDLC artifacts.
cf-sdlc-pr-review: ...	Review a pull request against project and SDLC expectations.
cf-sdlc-pr-status: ...	Summarize pull request state, checks, and unresolved review work.

Roadmap

Implemented:

• Repository-local cfs command-line interface.
• Minimal repository footprint with generated Studio and agent integration files ignored by git by default.
• AI coding tool integration generation.
• Concrete cf-* skill routing instead of generic prompts.
• User-gated sub-agent driven workflows where the AI coding tool supports sub-agents.
• Core skills for help, exploration, brainstorming, planning, coding, documentation, skill authoring, explanation, maps, kits, workspaces, and prompt debugging.
• Software Development Life Cycle (SDLC) kit with Product Requirements Document, Architecture Decision Record, DESIGN, DECOMPOSITION, FEATURE, implementation, impact analysis, reverse engineering, OpenSpec migration, pull request review, and pull request status skills.
• Customizable templates, rules, checklists, artifact formats, and skill behavior.
• Canonical Provenance Trace ID (CPT ID) traceability across documents, code, tests, and reviews.
• Review loops with findings browsing and explicit fix-scope approval before fix-writing dispatch.
• Deterministic validation for configured artifacts, structure, references, language policy, and guide tables of contents.
• Dependency map across documents and code.
• Multi-repository workspace support.
• Kit installation from GitHub, generic Git sources, and local paths.
• Mirror overrides for replacing official source locations with forks or internal mirrors.

Planned:

• Official and custom kit store: publish, register, discover, and distribute organization-specific kits.
• Dependency manager for kits when the kit store is available.
• Package distribution through Homebrew, Python Package Index (PyPI), and Scoop.
• Template-based, extensible prompts generated by the cfs tool.
• Visual Studio Code plugin for configuration, document visualization, kit management, and validation.
• Web application and hosted service with tight Cyber Wiki integration for document and code visualization, pull request work, configuration, team collaboration, and chat with skills.
• Global installation at the operating system level. Today Constructor Studio is installed per repository or workspace.
• Deterministic workflows with tight Kitsoki integration.

References

• Usage guide - first moves, skill selection, prompt patterns, workspaces, delegation, and common mistakes
• Installation and setup reference
• Configuration guide - artifacts, CPT IDs, templates, checklists, validation, kits, and dependency maps
• Kit management
• Dependency map
• AI agent tools guide - Claude Code, Cursor, Codex, Copilot, Windsurf, and host tradeoffs
• Project extensibility guide - organization-level composition and multi-repository patterns
• Migration from Cypilot

Feedback

Feedback, bug reports, use cases, and documentation fixes are welcome. Open an issue or discussion in the repository when something is unclear, broken, or missing.

Contributing

See CONTRIBUTING.md for local development, validation, and contribution rules.

License

Constructor Studio is licensed under the Apache License 2.0.