Skip to content

Commit c2df4f0

Browse files
KSemenenkoKSemenenko
committed
pages
1 parent 0825c0a commit c2df4f0

File tree

3 files changed

+353
-1
lines changed

3 files changed

+353
-1
lines changed

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,8 @@ jobs:
3131
run: |
3232
git fetch origin main --depth=2
3333
CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || echo "")
34-
if echo "$CHANGED" | grep -qE '^(README\.md|docs/)'; then
34+
# Release if any changes outside github-pages/ and .github/
35+
if echo "$CHANGED" | grep -qvE '^(github-pages/|\.github/)'; then
3536
echo "release=true" >> $GITHUB_OUTPUT
3637
else
3738
echo "release=false" >> $GITHUB_OUTPUT
@@ -93,6 +94,11 @@ jobs:
9394
9495
echo "</div>" >> github-pages/templates.md
9596
97+
- name: Copy TUTORIAL to github-pages
98+
run: |
99+
printf '%s\n' '---' 'layout: default' 'title: Tutorial' 'nav_order: 3' '---' '' > github-pages/tutorial.md
100+
cat TUTORIAL.md >> github-pages/tutorial.md
101+
96102
- name: Copy README to github-pages with TOC
97103
run: |
98104
WORDS=$(wc -w < README.md)

‎TUTORIAL.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
# Getting Started with MCAF
2+
3+
A practical guide to implementing MCAF in your repository.
4+
5+
---
6+
7+
## Quick Start Checklist
8+
9+
Get MCAF running in your repository in 5 steps:
10+
11+
- [ ] Create `docs/` folder with `Features/`, `ADR/`, `Testing/`, `Development/`
12+
- [ ] Copy `AGENTS.md` template to your repository root
13+
- [ ] Define `build`, `test`, `format`, `analyze` commands in `AGENTS.md`
14+
- [ ] Set up containerized test environment (Docker Compose or equivalent)
15+
- [ ] Configure static analyzers and add to CI pipeline
16+
17+
---
18+
19+
## Step-by-Step Implementation
20+
21+
### Step 1: Set Up Documentation Structure
22+
23+
Create the following folders:
24+
25+
```
26+
your-repo/
27+
├── docs/
28+
│ ├── Features/ # Feature specifications
29+
│ ├── ADR/ # Architecture Decision Records
30+
│ ├── Testing/ # Test strategy and flows
31+
│ ├── Development/ # Setup and workflow guides
32+
│ ├── API/ # API documentation (if applicable)
33+
│ └── Architecture/ # System diagrams and boundaries
34+
├── AGENTS.md # AI agent instructions
35+
└── README.md # Project overview
36+
```
37+
38+
### Step 2: Configure AGENTS.md
39+
40+
Copy the AGENTS.md template and customize:
41+
42+
1. Replace `{{ProjectName}}` and `{{Stack}}` with your values
43+
2. Add project-specific rules in Section 2
44+
3. Define your actual `build`, `test`, `format`, `analyze` commands in Section 7
45+
4. Add team preferences in Section 8
46+
47+
Example commands section:
48+
49+
```markdown
50+
## 7. Commands
51+
52+
- build: `npm run build`
53+
- test: `npm test`
54+
- format: `npm run format`
55+
- analyze: `npm run lint`
56+
```
57+
58+
### Step 3: Create Your First Feature Doc
59+
60+
Before implementing a feature, create `docs/Features/feature-name.md`:
61+
62+
```markdown
63+
# Feature: User Authentication
64+
65+
## Purpose
66+
Allow users to sign in with email and password.
67+
68+
## Business Rules
69+
- Email must be valid format
70+
- Password minimum 8 characters
71+
- Lock account after 5 failed attempts
72+
73+
## Main Flow
74+
1. User enters email and password
75+
2. System validates credentials
76+
3. System creates session and returns token
77+
78+
## Test Flows
79+
80+
### Positive
81+
- Valid credentials → returns token
82+
- Remember me checked → extended session
83+
84+
### Negative
85+
- Invalid email format → validation error
86+
- Wrong password → authentication error
87+
- Locked account → account locked error
88+
89+
## Definition of Done
90+
- [ ] All test flows pass
91+
- [ ] API documentation updated
92+
- [ ] No new analyzer warnings
93+
```
94+
95+
### Step 4: Set Up Test Environment
96+
97+
Create `docker-compose.test.yml` for dependencies:
98+
99+
```yaml
100+
version: '3.8'
101+
services:
102+
postgres:
103+
image: postgres:15
104+
environment:
105+
POSTGRES_DB: test
106+
POSTGRES_USER: test
107+
POSTGRES_PASSWORD: test
108+
ports:
109+
- "5432:5432"
110+
111+
redis:
112+
image: redis:7
113+
ports:
114+
- "6379:6379"
115+
```
116+
117+
Document in `docs/Development/setup.md`:
118+
119+
```markdown
120+
# Local Development Setup
121+
122+
## Prerequisites
123+
- Docker and Docker Compose
124+
- Node.js 18+
125+
126+
## Start Test Environment
127+
docker-compose -f docker-compose.test.yml up -d
128+
129+
## Run Tests
130+
npm test
131+
```
132+
133+
### Step 5: Configure CI Pipeline
134+
135+
Example GitHub Actions workflow:
136+
137+
```yaml
138+
name: CI
139+
on: [push, pull_request]
140+
141+
jobs:
142+
test:
143+
runs-on: ubuntu-latest
144+
services:
145+
postgres:
146+
image: postgres:15
147+
env:
148+
POSTGRES_DB: test
149+
POSTGRES_USER: test
150+
POSTGRES_PASSWORD: test
151+
ports:
152+
- 5432:5432
153+
154+
steps:
155+
- uses: actions/checkout@v4
156+
- uses: actions/setup-node@v4
157+
with:
158+
node-version: '18'
159+
160+
- run: npm ci
161+
- run: npm run build
162+
- run: npm test
163+
- run: npm run lint
164+
```
165+
166+
---
167+
168+
## Working with AI Agents
169+
170+
### Delegated Mode (Agent does most work)
171+
172+
Best for:
173+
- Bug fixes with clear reproduction steps
174+
- Features with complete documentation
175+
- Routine refactoring
176+
177+
Workflow:
178+
1. Write feature doc with test flows
179+
2. Point agent to the feature doc
180+
3. Agent implements and tests
181+
4. You review and merge
182+
183+
### Collaborative Mode (Working together)
184+
185+
Best for:
186+
- Complex features
187+
- Architectural changes
188+
- New integrations
189+
190+
Workflow:
191+
1. Discuss approach with agent
192+
2. Agent drafts, you guide
193+
3. Iterate on implementation
194+
4. Review together
195+
196+
### Consultative Mode (Agent advises)
197+
198+
Best for:
199+
- Security-sensitive code
200+
- Learning new codebase
201+
- Design exploration
202+
203+
Workflow:
204+
1. Ask agent to explain current code
205+
2. Discuss options and trade-offs
206+
3. You implement
207+
4. Agent reviews
208+
209+
---
210+
211+
## FAQ
212+
213+
### General
214+
215+
**Q: Does MCAF work with any programming language?**
216+
217+
A: Yes. MCAF is language-agnostic. The principles apply to any stack. You just need to define your specific `build`, `test`, `format`, and `analyze` commands.
218+
219+
**Q: Do I need all the documentation folders?**
220+
221+
A: Start with `Features/`, `ADR/`, and `Development/`. Add others as needed. The structure adapts to your project size.
222+
223+
**Q: What if my team doesn't have a dedicated QA?**
224+
225+
A: Developers take the QA perspective. The point is ensuring test coverage, not having a specific role.
226+
227+
### Testing
228+
229+
**Q: Why avoid mocking internal services?**
230+
231+
A: Mocks can hide integration bugs. Real containers catch issues that mocks miss. If you can't test without mocks, it's often a design smell.
232+
233+
**Q: How much test coverage is enough?**
234+
235+
A: Every significant behaviour needs at least one integration/API/UI test. Focus on workflows, not percentages.
236+
237+
**Q: What about unit tests?**
238+
239+
A: Use them for complex internal logic. But don't rely solely on unit tests for behaviour verification.
240+
241+
### AI Agents
242+
243+
**Q: Which AI agents work with MCAF?**
244+
245+
A: Any AI coding assistant that can read files. Claude, GPT, Copilot, Cursor — all work. Point them to `AGENTS.md`.
246+
247+
**Q: How does the agent learn my preferences?**
248+
249+
A: Update `AGENTS.md` when you give feedback. The agent reads it before each task. Chat isn't memory — the file is.
250+
251+
**Q: Can the agent merge code?**
252+
253+
A: No. Humans always make the final merge decision. The agent prepares, you approve.
254+
255+
### Adoption
256+
257+
**Q: Can I adopt MCAF gradually?**
258+
259+
A: Yes. Start with `AGENTS.md` and one feature doc. Add structure as you go.
260+
261+
**Q: How do I get my team on board?**
262+
263+
A: Start with one project. Show results. The framework proves itself through predictable, tested code.
264+
265+
---
266+
267+
## Common Mistakes
268+
269+
### 1. Writing code before docs
270+
271+
**Wrong:** Jump into coding, document later.
272+
273+
**Right:** Write feature doc with test flows first. Then implement.
274+
275+
### 2. Mocking everything
276+
277+
**Wrong:** Mock database, cache, queues for "fast" tests.
278+
279+
**Right:** Use real containers. Catch real integration issues.
280+
281+
### 3. Treating AGENTS.md as static
282+
283+
**Wrong:** Set up once, never update.
284+
285+
**Right:** Update after every significant feedback or pattern discovery.
286+
287+
### 4. Skipping the plan step
288+
289+
**Wrong:** Start coding immediately for "simple" changes.
290+
291+
**Right:** Even small changes benefit from explicit planning.
292+
293+
### 5. Ignoring analyzer warnings
294+
295+
**Wrong:** Suppress warnings to make CI green.
296+
297+
**Right:** Fix warnings or document explicit exceptions.
298+
299+
---
300+
301+
## Example Project Structure
302+
303+
A complete MCAF-compliant repository:
304+
305+
```
306+
my-project/
307+
├── .github/
308+
│ └── workflows/
309+
│ └── ci.yml
310+
├── docs/
311+
│ ├── Features/
312+
│ │ ├── user-auth.md
313+
│ │ └── payment-flow.md
314+
│ ├── ADR/
315+
│ │ ├── 001-database-choice.md
316+
│ │ └── 002-auth-strategy.md
317+
│ ├── Testing/
318+
│ │ └── strategy.md
319+
│ ├── Development/
320+
│ │ └── setup.md
321+
│ └── API/
322+
│ └── endpoints.md
323+
├── src/
324+
│ └── ...
325+
├── tests/
326+
│ ├── integration/
327+
│ ├── api/
328+
│ └── e2e/
329+
├── docker-compose.test.yml
330+
├── AGENTS.md
331+
└── README.md
332+
```
333+
334+
---
335+
336+
## Next Steps
337+
338+
1. Copy templates from [Templates](/templates)
339+
2. Read the full [MCAF Guide](/) for detailed specifications
340+
3. Set up your first feature using the workflow above
341+
4. Iterate and improve your `AGENTS.md` as you learn
342+
343+
---
344+
345+
*Need help? Open an issue on [GitHub](https://github.com/managedcode/MCAF).*

‎github-pages/_layouts/default.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
<a href="{{ '/' | relative_url }}" class="nav-logo">{{ site.title }}</a>
8585
<div class="nav-links">
8686
<a href="{{ '/' | relative_url }}" {% if page.url == '/' %}class="active"{% endif %}>Guide</a>
87+
<a href="{{ '/tutorial' | relative_url }}" {% if page.url == '/tutorial.html' %}class="active"{% endif %}>Tutorial</a>
8788
<a href="{{ '/templates' | relative_url }}" {% if page.url == '/templates.html' %}class="active"{% endif %}>Templates</a>
8889
<a href="https://github.com/managedcode/MCAF" target="_blank" rel="noopener">GitHub</a>
8990
<a href="https://managed-code.com" target="_blank" rel="noopener" class="nav-brand">ManagedCode</a>

0 commit comments

Comments
 (0)