Skip to content

Commit e8d6732

Browse files
KSemenenkoKSemenenko
committed
Unify MCAF skill loop, add skill QA gate, and rename Guide to Concepts
1 parent 3842617 commit e8d6732

File tree

47 files changed

+1746
-262
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+1746
-262
lines changed

‎.github/workflows/jekyll-gh-pages.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,7 @@ jobs:
327327
cat > github-pages/index.md << 'EOF'
328328
---
329329
layout: default
330-
title: Guide
330+
title: Concepts
331331
description: MCAF is a skill-first framework for building real software with AI coding agents using AGENTS.md, repository-native skills, and automated verification.
332332
keywords: MCAF, Coding AI Framework, AGENTS.md, AI-assisted development, AI coding skills, real software, Codex, Claude Code
333333
is_home: true

‎README.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# MCAF Guide
1+
# MCAF Concepts
22

33
**Managed Code Coding AI Framework**
44

@@ -28,8 +28,9 @@ MCAF has three core elements:
2828
- **Verification** — tests and analyzers are the decision makers, not opinions.
2929
- **Instructions** — root and local `AGENTS.md` files define how agents work here.
3030

31-
This Guide defines the framework.
32-
Repository `AGENTS.md` files apply it to a specific solution.
31+
These concepts define the framework (the "what" and "why").
32+
`TUTORIAL.md` is the bootstrap procedure (the "how").
33+
Repository `AGENTS.md` files apply both to a specific solution.
3334

3435
### 1.1 Bootstrap Surface
3536

@@ -98,6 +99,12 @@ A skill contains:
9899
- `assets/` — output assets or templates used by the workflow
99100
- `scripts/` — deterministic helpers when they add reliability
100101

102+
Run skill quality validation before merging skill changes:
103+
104+
```bash
105+
./scripts/verify_mcaf_skills.sh
106+
```
107+
101108
Recommended target locations in a consuming repo:
102109

103110
- Codex: `.codex/skills/`

‎TUTORIAL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Getting Started with MCAF v1.2
22

33
This tutorial is the canonical bootstrap flow for humans and agents.
4+
It is intentionally separate from `README.md`:
5+
- `README.md` explains MCAF concepts
6+
- `TUTORIAL.md` explains installation and update steps
47

58
There is no shell installer in `v1.2`.
69
The install path is URL-first and simple:

‎docs/templates/AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,13 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
168168
- required change
169169
- constraints and risks
170170
- For non-trivial work, keep a written implementation plan in the feature doc, ADR, issue, or PR description.
171+
- Use the Ralph Loop for every non-trivial task:
172+
- plan in detail before coding or document edits
173+
- include ordered final validation skills in the plan, with reason for each skill
174+
- require each selected skill to produce a concrete action, artifact, or verification outcome
175+
- execute one planned step at a time
176+
- review findings, apply fixes, and rerun relevant verification
177+
- update the plan and repeat until done criteria are met or an explicit exception is documented
171178
- Implement code and tests together.
172179
- Run verification in layers:
173180
- changed tests

‎github-pages/404.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
<div class="error-page">
99
<h1>404</h1>
1010
<p class="error-subtitle">Vibe coding without MCAF again?</p>
11-
<p class="error-joke">Yeah, we get it. This page doesn't exist.<br>Maybe it's time to read the guide or check out ManagedCode.</p>
11+
<p class="error-joke">Yeah, we get it. This page doesn't exist.<br>Maybe it's time to read the concepts or check out ManagedCode.</p>
1212
<div class="error-actions">
13-
<a href="{{ '/' | relative_url }}" class="btn btn-primary">Read MCAF Guide</a>
13+
<a href="{{ '/' | relative_url }}" class="btn btn-primary">Read MCAF Concepts</a>
1414
<a href="https://www.managed-code.com/" target="_blank" rel="noopener" class="btn">Visit ManagedCode</a>
1515
</div>
1616
</div>

‎github-pages/_layouts/default.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@
180180
<nav class="nav">
181181
<a href="{{ '/' | relative_url }}" class="nav-logo">{{ site.title }}</a>
182182
<div class="nav-links">
183-
<a href="{{ '/' | relative_url }}" {% if page.url == '/' %}class="active"{% endif %}>Guide</a>
183+
<a href="{{ '/' | relative_url }}" {% if page.url == '/' %}class="active"{% endif %}>Concepts</a>
184184
<a href="{{ '/tutorial' | relative_url }}" {% if page.url == '/tutorial.html' %}class="active"{% endif %}>Tutorial</a>
185185
<a href="{{ '/templates' | relative_url }}" {% if page.url == '/templates.html' %}class="active"{% endif %}>Templates</a>
186186
<a href="{{ '/skills' | relative_url }}" {% if page.url == '/skills.html' %}class="active"{% endif %}>Skills</a>

‎github-pages/index.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
layout: default
3-
title: Guide
4-
description: MCAF is a framework that solves the problem of unpredictable AI coding. Build real production software with Coding AI agents using structured context, automated tests as verification gates, and AGENTS.md instructions. Vibe coding that actually works.
5-
keywords: MCAF, Coding AI Framework, AGENTS.md, vibe coding, AI-assisted development, AI-assisted coding, real software, production code, Claude Code, Codex, Gemini, ChatGPT, Cursor, GitHub Copilot, Windsurf, Cline, Aider, ManagedCode
3+
title: Concepts
4+
description: MCAF is a skill-first framework for building real software with AI coding agents using AGENTS.md, repository-native skills, and automated verification.
5+
keywords: MCAF, Coding AI Framework, AGENTS.md, AI-assisted development, AI coding skills, real software, Codex, Claude Code
66
is_home: true
77
nav_order: 1
88
---

‎scripts/verify_mcaf_skills.sh‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
5+
skills_dir="$repo_root/skills"
6+
7+
required_headers=(
8+
"## Trigger On"
9+
"## Value"
10+
"## Do Not Use For"
11+
"## Inputs"
12+
"## Quick Start"
13+
"## Workflow"
14+
"## Deliver"
15+
"## Validate"
16+
"## Ralph Loop"
17+
"### Required Result Format"
18+
"## Load References"
19+
"## Example Requests"
20+
)
21+
22+
fail_count=0
23+
checked_count=0
24+
25+
for skill_file in "$skills_dir"/mcaf-*/SKILL.md; do
26+
checked_count=$((checked_count + 1))
27+
skill_name="$(basename "$(dirname "$skill_file")")"
28+
local_fail=0
29+
30+
for header in "${required_headers[@]}"; do
31+
if ! rg -q "^${header}$" "$skill_file"; then
32+
echo "[FAIL] $skill_name missing header: $header"
33+
local_fail=1
34+
fi
35+
done
36+
37+
workflow_steps="$(awk '
38+
/^## Workflow$/ {sec=1; next}
39+
/^## / && sec {sec=0}
40+
sec && /^[0-9]+\./ {c++}
41+
END{print c+0}
42+
' "$skill_file")"
43+
44+
if [[ "$workflow_steps" -lt 3 ]]; then
45+
echo "[FAIL] $skill_name has too few workflow steps: $workflow_steps (min: 3)"
46+
local_fail=1
47+
fi
48+
49+
deliver_bullets="$(awk '
50+
/^## Deliver$/ {sec=1; next}
51+
/^## / && sec {sec=0}
52+
sec && /^- / {c++}
53+
END{print c+0}
54+
' "$skill_file")"
55+
56+
validate_bullets="$(awk '
57+
/^## Validate$/ {sec=1; next}
58+
/^## / && sec {sec=0}
59+
sec && /^- / {c++}
60+
END{print c+0}
61+
' "$skill_file")"
62+
63+
if [[ "$deliver_bullets" -lt 1 ]]; then
64+
echo "[FAIL] $skill_name has empty Deliver section"
65+
local_fail=1
66+
fi
67+
68+
if [[ "$validate_bullets" -lt 1 ]]; then
69+
echo "[FAIL] $skill_name has empty Validate section"
70+
local_fail=1
71+
fi
72+
73+
if ! rg -q "final validation skills" "$skill_file"; then
74+
echo "[FAIL] $skill_name Ralph Loop is missing final validation skills requirement"
75+
local_fail=1
76+
fi
77+
78+
if [[ "$local_fail" -eq 0 ]]; then
79+
echo "[OK] $skill_name"
80+
else
81+
fail_count=$((fail_count + 1))
82+
fi
83+
done
84+
85+
echo
86+
echo "Checked: $checked_count skills"
87+
echo "Failed : $fail_count skills"
88+
89+
if [[ "$fail_count" -ne 0 ]]; then
90+
exit 1
91+
fi
92+

‎skills/mcaf-adr-writing/SKILL.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ compatibility: "Requires repository write access; produces Markdown ADRs with Me
1212
- a design decision has meaningful trade-offs that should be recorded
1313
- a repo-wide engineering policy needs a durable rationale
1414

15+
## Value
16+
17+
- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
18+
- reduce ambiguity through explicit planning, verification, and final validation skills
19+
- leave reusable project context so future tasks are faster and safer
20+
1521
## Do Not Use For
1622

1723
- feature-level behaviour details without an architecture decision
@@ -24,6 +30,12 @@ compatibility: "Requires repository write access; produces Markdown ADRs with Me
2430
- the nearest `AGENTS.md`
2531
- current constraints, options, and risks
2632

33+
## Quick Start
34+
35+
1. Read the nearest `AGENTS.md` and confirm scope and constraints.
36+
2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.
37+
3. Return the `Required Result Format` with concrete artifacts and verification evidence.
38+
2739
## Workflow
2840

2941
1. Start from the concrete decision that must be made now.
@@ -49,6 +61,33 @@ compatibility: "Requires repository write access; produces Markdown ADRs with Me
4961
- implementation impact is clear
5062
- a future engineer can understand why this path was chosen
5163

64+
## Ralph Loop
65+
66+
Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
67+
68+
1. Plan first (mandatory):
69+
- analyze current state
70+
- define target outcome, constraints, and risks
71+
- write a detailed execution plan
72+
- list final validation skills to run at the end, with order and reason
73+
2. Execute one planned step and produce a concrete delta.
74+
3. Review the result and capture findings with actionable next fixes.
75+
4. Apply fixes in small batches and rerun the relevant checks or review steps.
76+
5. Update the plan after each iteration.
77+
6. Repeat until outcomes are acceptable or only explicit exceptions remain.
78+
7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
79+
80+
### Required Result Format
81+
82+
- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`
83+
- `plan`: concise plan and current iteration step
84+
- `actions_taken`: concrete changes made
85+
- `validation_skills`: final skills run, or skipped with reasons
86+
- `verification`: commands, checks, or review evidence summary
87+
- `remaining`: top unresolved items or `none`
88+
89+
For setup-only requests with no execution, return `status: configured` and exact next commands.
90+
5291
## Load References
5392

5493
- start with `references/adr-template.md`

‎skills/mcaf-agile-delivery/SKILL.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ compatibility: "Requires repository access only when the repo stores delivery do
1212
- delivery process is vague, too heavy, or living only in chat
1313
- recurring team pain needs to become durable repo guidance
1414

15+
## Value
16+
17+
- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
18+
- reduce ambiguity through explicit planning, verification, and final validation skills
19+
- leave reusable project context so future tasks are faster and safer
20+
1521
## Do Not Use For
1622

1723
- repo governance that belongs in `AGENTS.md`
@@ -23,6 +29,12 @@ compatibility: "Requires repository access only when the repo stores delivery do
2329
- backlog, role, ceremony, and feedback mechanisms that already exist
2430
- where the team stores durable agreements, if anywhere
2531

32+
## Quick Start
33+
34+
1. Read the nearest `AGENTS.md` and confirm scope and constraints.
35+
2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.
36+
3. Return the `Required Result Format` with concrete artifacts and verification evidence.
37+
2638
## Workflow
2739

2840
1. Keep delivery artefacts concrete:
@@ -46,6 +58,33 @@ compatibility: "Requires repository access only when the repo stores delivery do
4658
- roles and rituals are explicit enough to use
4759
- recurring pain is converted into a durable artifact, not more chat
4860

61+
## Ralph Loop
62+
63+
Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
64+
65+
1. Plan first (mandatory):
66+
- analyze current state
67+
- define target outcome, constraints, and risks
68+
- write a detailed execution plan
69+
- list final validation skills to run at the end, with order and reason
70+
2. Execute one planned step and produce a concrete delta.
71+
3. Review the result and capture findings with actionable next fixes.
72+
4. Apply fixes in small batches and rerun the relevant checks or review steps.
73+
5. Update the plan after each iteration.
74+
6. Repeat until outcomes are acceptable or only explicit exceptions remain.
75+
7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
76+
77+
### Required Result Format
78+
79+
- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`
80+
- `plan`: concise plan and current iteration step
81+
- `actions_taken`: concrete changes made
82+
- `validation_skills`: final skills run, or skipped with reasons
83+
- `verification`: commands, checks, or review evidence summary
84+
- `remaining`: top unresolved items or `none`
85+
86+
For setup-only requests with no execution, return `status: configured` and exact next commands.
87+
4988
## Load References
5089

5190
- read `references/agile-delivery.md` first

0 commit comments

Comments
 (0)