Skip to content

Enhance update command and CI with minimal footprint support #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ainetx merged 5 commits into from
Jun 7, 2026
Merged

Enhance update command and CI with minimal footprint support #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dc14a24
feat(update): enhance update command to support kit updates with --wi…
ainetx Jun 7, 2026
1851e0a
feat(ci): add bootstrap repair step to CI jobs and update Makefile co…
ainetx Jun 7, 2026
98318af
feat(init): support minimal footprint installs
ainetx Jun 7, 2026
7bb8417
docs(guides): sync minimal footprint guidance
ainetx Jun 7, 2026
d26fc7e
fix(update): handle footprint review findings
ainetx Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions .bootstrap/config/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,22 @@ This directory contains **user-editable** configuration files.

## Files

- `core.toml` — project settings (system name, slug, kit references)
- `core.toml` — project settings, install tracking policy, and kit references
- `artifacts.toml` — artifacts registry (systems, ignore patterns)
- `AGENTS.md` — custom agent navigation rules (add your own WHEN rules here)
- `SKILL.md` — custom skill extensions (add your own skill instructions here)

## Directories

- `kits/{slug}/` — editable installed kit content: templates, rules,
checklists, constraints, workflows, scripts, and skill surfaces.
Modify these files directly when you need project-local customization.
- `kits/{slug}/` — kit files (SKILL.md, AGENTS.md, artifacts/, codebase/, workflows/, scripts/).
Each kit has its own git tracking policy. Tracked kits are editable repository
content. Ignored kits are generated local content and may be overwritten by
Studio repair/update flows.

## Tips

- `AGENTS.md` and `SKILL.md` start empty. Add any project-specific rules or
skill instructions here — they will be picked up alongside installed kit content.
- Use `cfs kit update` to update installed kit files from their registered source.
Inspect the diff before accepting upstream changes over local customizations.
skill instructions here — they will be picked up alongside the kit ones.
- Kit files can be edited directly when that kit is tracked. `cfs kit update`
shows a diff for tracked kit changes. Top-level `cfs update` does not update
kit files unless called with `--with-kits yes`.
7 changes: 7 additions & 0 deletions .bootstrap/config/core.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ format = "CFS"
path = "config/kits/sdlc"
version = "v1.1.1"
source = "github:constructorfabric/studio-kit-sdlc"
tracking = "ignored"

[kits.sdlc.resources]
[kits.sdlc.resources.adr_template]
Expand Down Expand Up @@ -153,3 +154,9 @@ conf_version = "1.0.0"
[integrations]
[integrations.ralphex]
executable_path = ""

[install]
version_source = "project_config"
kit_tracking = "tracked"
runtime_tracking = "ignored"
agent_tracking = "ignored"
9 changes: 9 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,9 @@ jobs:
with:
python-version: '3.12'

- name: Repair bootstrap
run: make bootstrap-repair

- name: Check spec coverage
run: make spec-coverage

Expand All @@ -152,6 +155,9 @@ jobs:
with:
python-version: ${{ matrix.python-version }}

- name: Repair bootstrap
run: make bootstrap-repair

- name: Validate core methodology
run: make CFS="python3 .bootstrap/.core/skills/studio/scripts/studio.py" validate

Expand All @@ -172,5 +178,8 @@ jobs:
with:
python-version: ${{ matrix.python-version }}

- name: Repair bootstrap
run: make bootstrap-repair

- name: Validate all registered kits
run: make CFS="python3 .bootstrap/.core/skills/studio/scripts/studio.py" validate-kits
66 changes: 50 additions & 16 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,25 +31,61 @@ build/
# Claude Code local settings (user-specific)
.claude/settings.local.json

# Constructor Studio generated agent integrations (local-only).
# Keep these scoped to Constructor Studio-owned output names so unrelated
# user files in the same host directories remain visible to git.
.agents/skills/cf*/SKILL.md
.claude/agents/cf-*.md
.claude/agents/storytelling-*.md
.claude/skills/cf*/SKILL.md
.codex/.cf-installed
.codex/agents/cf-*.toml
# BEGIN Constructor Studio
# Generated Constructor Studio runtime and agent integration files.
# Files matched here are owned by Constructor Studio and may be overwritten.
.bootstrap/.core/
.bootstrap/.gen/
.agents/skills/cf/
.agents/skills/cf-*/
.agents/skills/studio-*/
.agents/skills/cypilot-*/
.agents/skills/cf-constructor-*/
.codex/agents/cf*.toml
.codex/agents/studio-*.toml
.codex/agents/cypilot-*.toml
.codex/agents/cf-constructor-*.toml
.codex/agents/storytelling-*.toml
.cursor/agents/cf-*.md
.cursor/agents/storytelling-*.md
.codex/.cf-installed
.codex/.constructor-studio-installed
.claude/skills/cf/
.claude/skills/cf-*/
.claude/commands/cf*.md
.claude/commands/studio-*.md
.claude/commands/cypilot-*.md
.claude/commands/cf-constructor-*.md
.claude/agents/cf*.md
.claude/agents/studio-*.md
.claude/agents/cypilot-*.md
.claude/agents/cf-constructor-*.md
.claude/agents/storytelling-*.md
.cursor/commands/cf*.md
.cursor/commands/studio-*.md
.cursor/commands/cypilot-*.md
.cursor/commands/cf-constructor-*.md
.cursor/agents/cf*.md
.cursor/agents/studio-*.md
.cursor/agents/cypilot-*.md
.cursor/agents/cf-constructor-*.md
.cursor/agents/storytelling-*.md
.github/prompts/cf*.prompt.md
.github/prompts/studio-*.prompt.md
.github/prompts/cypilot-*.prompt.md
.github/prompts/cf-constructor-*.prompt.md
.github/agents/cf*.md
.github/agents/studio-*.md
.github/agents/cypilot-*.md
.github/agents/cf-constructor-*.md
.github/agents/storytelling-*.md
.github/.cf-installed
.github/agents/cf-*.agent.md
.github/agents/storytelling-*.agent.md
.github/.constructor-studio-installed
.github/copilot-instructions.md
.github/prompts/cf*.prompt.md
.windsurf/workflows/cf*.md
.windsurf/workflows/studio-*.md
.windsurf/workflows/cypilot-*.md
.windsurf/workflows/cf-constructor-*.md
.bootstrap/config/kits/sdlc/
# END Constructor Studio

*.backup

Expand Down Expand Up @@ -80,8 +116,6 @@ cypilot-flow-layers-2a.drawio.svg
Spaider.code-workspace

# Cypilot plans (ephemeral)
.bootstrap/.core/
.bootstrap/.gen/
.bootstrap/.plans/.archive/
.bootstrap/.plans/analyze-path-skills-cypilot-scripts-cypilot/
.bootstrap/.plans/analyze-path-current-branch-vs-main-comprehensive/
Expand Down
46 changes: 25 additions & 21 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# @cpt-algo:cpt-studio-spec-init-structure-change-infrastructure:p1
.PHONY: test test-verbose test-quick test-coverage test-coverage-diff validate validate-examples validate-feature validate-code validate-code-feature self-check validate-kits validate-kits-sdlc vulture vulture-ci pylint install install-pipx install-proxy install-prompt-tests clean help check-pytest check-pytest-cov check-pipx check-vulture check-pylint check-versions check-prompt-tests update seed-cache ensure-bootstrap generate-agents spec-coverage ci lint-ci test-prompts test-prompts-view
.PHONY: test test-verbose test-quick test-coverage test-coverage-diff validate validate-examples validate-feature validate-code validate-code-feature self-check validate-kits validate-kits-sdlc vulture vulture-ci pylint install install-pipx install-proxy install-prompt-tests clean help check-pytest check-pytest-cov check-pipx check-vulture check-pylint check-versions check-prompt-tests bootstrap-init bootstrap-repair update update-local seed-cache ensure-bootstrap generate-agents spec-coverage ci lint-ci test-prompts test-prompts-view

# Detect container architecture for act (arm64 on Apple Silicon, amd64 otherwise)
UNAME_M := $(shell uname -m)
Expand Down Expand Up @@ -59,7 +59,10 @@ help:
@echo " make install-prompt-tests - Pre-cache promptfoo for cf-skill UX tests"
@echo " make test-prompts - Run cf-skill UX pilot (claude + codex)"
@echo " make test-prompts-view - Open promptfoo HTML report for last run"
@echo " make update - Update .bootstrap from local source"
@echo " make bootstrap-init - Initialize .bootstrap from local source"
@echo " make bootstrap-repair - Repair generated .bootstrap runtime files"
@echo " make update-local - Update .bootstrap from local source"
@echo " make update - Alias for update-local"
@echo " make generate-agents - Generate all local agent integrations"
@echo " make clean - Remove Python cache files"
@echo " make help - Show this help message"
Expand Down Expand Up @@ -207,34 +210,35 @@ spec-coverage: ensure-bootstrap
check-versions:
@$(PYTHON) scripts/check_versions.py

# Update .bootstrap from local source
update:
# Initialize .bootstrap from local source. Repeat runs repair generated runtime files.
bootstrap-init: seed-cache
@echo "Initializing .bootstrap from local source..."
$(PYTHON) $(SOURCE_STUDIO) init --project-root . --install-dir .bootstrap --kit-tracking tracked --kit-tracking sdlc=ignored --yes

# Repair generated .bootstrap runtime files without updating tracked kit files.
bootstrap-repair: seed-cache
@echo "Repairing generated .bootstrap runtime files from local source..."
$(PYTHON) $(SOURCE_STUDIO) init --project-root . --install-dir .bootstrap --kit-tracking tracked --kit-tracking sdlc=ignored --yes

# Backward-compatible alias: update means local self-hosted update in this repo.
update: update-local

# Update .bootstrap from local source. Kit files are skipped by default by cfs update.
update-local: seed-cache
@if [ ! -f "$(BOOTSTRAP_STUDIO)" ]; then \
$(MAKE) seed-cache; \
$(PYTHON) $(SOURCE_STUDIO) update --from-dir . -y; \
elif [ "$(CFS)" = "cfs" ] && command -v cfs >/dev/null 2>&1; then \
cfs update --source . --force; \
elif [ -f "$(BOOTSTRAP_STUDIO)" ]; then \
$(PYTHON) $(BOOTSTRAP_STUDIO) update --from-dir . -y; \
$(PYTHON) $(SOURCE_STUDIO) init --project-root . --install-dir .bootstrap --kit-tracking tracked --kit-tracking sdlc=ignored --yes; \
else \
$(PYTHON) $(SOURCE_STUDIO) update --from-dir . -y; \
$(PYTHON) $(SOURCE_STUDIO) update --project-root . -y; \
fi

seed-cache:
@echo "Seeding Constructor Studio cache from tracked source..."
@rm -rf "$$HOME/.cf-studio/cache"
@mkdir -p "$$HOME/.cf-studio/cache"
@cp -R requirements schemas workflows skills architecture "$$HOME/.cf-studio/cache/"
@if [ -d .bootstrap/config/kits ]; then \
mkdir -p "$$HOME/.cf-studio/cache/kits"; \
cp -R .bootstrap/config/kits/* "$$HOME/.cf-studio/cache/kits/"; \
find "$$HOME/.cf-studio/cache/kits" -name whatsnew.toml -type f -delete; \
fi
PYTHONPATH=src $(PYTHON) scripts/seed_local_cache.py .

ensure-bootstrap:
@if [ ! -f "$(BOOTSTRAP_STUDIO)" ]; then \
echo "Bootstrap studio entrypoint missing; running make update..."; \
$(MAKE) update; \
echo "Bootstrap studio entrypoint missing; running make bootstrap-init..."; \
$(MAKE) bootstrap-init; \
fi

generate-agents: ensure-bootstrap
Expand Down
22 changes: 12 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,18 @@ After `cfs init` and `cfs generate-agents`, Constructor Studio typically adds a

This repo-installed control surface is how Constructor Studio becomes operationally real inside a repository rather than staying a chat convention. It is also the first concrete proof surface most teams can inspect directly: what is generated, what remains user-editable, what is optional, and what deterministic validation can see.

- **Generated** — AI coding tool integration files and repository wiring
- **User-editable** — project configuration, rules, and any installed kit content meant for local use
- **Generated** — runtime files, generated AI coding tool integration files, and repository wiring; these are gitignored by default and can be repaired by Studio
- **User-editable** — project configuration, rules, and any kit content you choose to track in git
- **Optional** — installed kit content extends the base platform only when you want a more opinionated delivery model
- **Validator-visible** — artifacts, plans, and configuration participate in deterministic `cfs` checks when those configured surfaces are in use

| Surface | Typical location | Ownership |
|---|---|---|
| Setup directory | `.cf-studio/` | Created by setup; contains both generated and user-editable material |
| Host integration files | `.windsurf/`, `.cursor/`, `.claude/`, `.github/`, `.codex/`, `.agents/` | Generated by `cfs generate-agents`; regenerate when host integration changes |
| Setup directory | `.cf-studio/` | Created by setup; contains generated runtime files and user-editable config |
| Runtime files | `.cf-studio/.core/`, `.cf-studio/.gen/` | Generated by Studio; gitignored by default; repaired by `cfs init`/`cfs update` |
| Host integration files | `.windsurf/`, `.cursor/`, `.claude/`, `.github/`, `.codex/`, `.agents/` | Generated by `cfs generate-agents`; gitignored by default; regenerate when host integration changes |

@coderabbitai coderabbitai Bot Jun 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use official platform capitalization (“GitHub”) in host integration examples.

Line 71 and Line 520 currently imply lowercase branding via .github/ in prose context. Please keep the directory path as-is but refer to the platform name as GitHub in surrounding wording for consistency in user-facing docs.

Also applies to: 520-520

🧰 Tools
🪛 LanguageTool

[uncategorized] ~71-~71: The official name of this software platform is spelled with a capital “H”.
Context: ...| .windsurf/, .cursor/, .claude/, .github/, .codex/, .agents/ | Generated by...

(GITHUB)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 71, Update the README prose that references the host
integration entry containing the `.github/` token to use the official platform
capitalization "GitHub" (keep the directory path `.github/` unchanged), and
apply the same capitalization correction for the other occurrence that mentions
`.github/`; locate the table row or sentence that lists `.github/` and change
surrounding wording from lowercase "github" to "GitHub" for consistency in
user-facing docs.

Source: Linters/SAST tools

| Project config | `.cf-studio/config/` | User-editable and reviewable in the repo |
| Installed kit content | `.cf-studio/config/kits/{slug}/` | User-editable local delivery surface for that kit |
| Installed kit content | `.cf-studio/config/kits/{slug}/` | Tracked or ignored per kit; tracked kits are editable repo content, ignored kits are generated local content |
| Self-hosted bootstrap copy in this repo only | `.bootstrap/` | Contributor-only special case; not the normal user-project layout |

### Core platform and optional kits
Expand Down Expand Up @@ -479,9 +480,9 @@ Constructor Studio works across multiple AI coding tools through the same portab
cfs generate-agents
```

`cfs init` and `cfs generate-agents` are one-time repository bootstrap steps, not steps every downstream user must repeat. (Contributors re-run `make generate-agents` to refresh local integrations after updates; the "one-time" qualifier applies to initial project initialization.)
`cfs init` and `cfs generate-agents` are one-time repository bootstrap steps, not steps every downstream user must repeat. `cfs init` is also safe to rerun later: in an initialized repository it repairs generated Studio runtime files and agent integrations using the version already pinned in the project.

This creates a default setup directory `.cf-studio/`, generated AI coding tool integration files, and user-editable configuration under `config/` inside that setup directory.
This creates a default setup directory `.cf-studio/`, generated AI coding tool integration files, and user-editable configuration under `config/` inside that setup directory. Generated runtime files and generated agent integrations are gitignored by default. Kit files are tracked or ignored per kit, depending on the choices you make during setup.

3. **Activate Constructor Studio** in the AI coding tool chat:
```text
Expand All @@ -507,15 +508,16 @@ For detailed host-specific setup, troubleshooting, and operational walkthroughs,

## Configuration files

The main top-level user-editable configuration lives under `config/` inside your Constructor Studio setup directory. Other parts of the setup directory may contain generated or supporting material, and installed kits can add their own editable surfaces.
The main top-level user-editable configuration lives under `config/` inside your Constructor Studio setup directory. Other parts of the setup directory contain generated or supporting material, and installed kits can add tracked editable surfaces or ignored generated local surfaces.

A quick ownership rule:

| Surface | Ownership |
|---|---|
| `.cf-studio/config/` | User-editable control surface |
| `.cf-studio/config/kits/{slug}/` | Editable installed-kit content |
| Host integration files such as `.windsurf/`, `.cursor/`, `.claude/`, `.github/`, `.codex/`, `.agents/` | Generated by `cfs generate-agents` |
| `.cf-studio/.core/`, `.cf-studio/.gen/` | Generated runtime files; gitignored by default |
| `.cf-studio/config/kits/{slug}/` | Tracked or ignored per kit |
| Host integration files such as `.windsurf/`, `.cursor/`, `.claude/`, `.github/`, `.codex/`, `.agents/` | Generated by `cfs generate-agents`; gitignored by default |
| `.bootstrap/` | Self-hosted contributor-only context |

You do not need full configuration mastery immediately. Treat these as the main top-level control files you can inspect, review, edit, and version in the repository.
Expand Down
Loading
Loading