Purpose: This file contains STRICT, ENFORCEABLE rules. Unlike AI_GUIDELINES.md (philosophy and best practices), this file is a CONTRACT that AI agents MUST follow. Violations MUST be reported to the user.
Sync: This file MUST be synced to all projects. When updating, sync to ~/Documents/kuro-rules (master copy).
AI agents MUST read this file at the START of every session, BEFORE any other action.
ACTION: Read AGENTS.md (this file) first
VERIFY: Confirm to user "I have read AGENTS.md and will enforce all rules"
IF agent starts working without reading rules:
- STOP immediately
- READ AGENTS.md
- RESTART the task with rules in context
Project CANNOT exceed 10% progress until Mom Test is COMPLETE. No production code allowed during Mom Test phase.
Before ANY code implementation, VERIFY ALL of the following:
| Requirement | Verification Method |
|---|---|
| Minimum 5 interviews | Check mom_test_results.md has 5+ interview entries |
mom_test_script.md exists |
File exists with EN/FR interview questions |
mom_test_results.md exists |
File exists with documented interviews |
decision.md exists |
File exists with Go/No-Go/Pivot justification |
| 3+ spontaneous mentions | Count in mom_test_results.md |
| 2+ solution seekers | Count in mom_test_results.md |
IF any checklist item is FALSE:
ACTION: STOP implementation immediately
ACTION: SET progress to 10% maximum
ACTION: REPORT missing deliverables to user
ACTION: COMPLETE missing deliverables before proceeding
DO NOT: Write production code
DO NOT: Create architecture documents beyond brainstorming
- Collecting interviews
- Creating
mom_test_script.md - Documenting in
mom_test_results.md - Creating
decision.md - Brainstorming in
ideas.md(NO production code) - Discussing approaches with user
- Writing production code
- Implementing features
- Creating architecture beyond high-level brainstorming
- Setting progress above 10%
Every project MUST track progress in SESSION_SUMMARY.md with PESSIMISTIC estimates.
| Component | Weight | When Complete |
|---|---|---|
| Mom Test | 10% | All deliverables done, decision made |
| Core functionality | 40% | All features working and tested |
| Test coverage (60%+) | 20% | Coverage report shows 60%+ |
| Security hardening | 10% | All scans pass (bandit, safety, etc.) |
| CI/CD & DevOps | 10% | Pipeline configured and passing |
| Documentation | 10% | README, CHANGELOG, API docs complete |
BEFORE reporting progress:
CALCULATE: Sum of completed components
SUBTRACT: 10-15% for optimism bias
VERIFY: Does this match reality?
IF doubt: Subtract another 10%
IF progress > actual completion:
ACTION: Recalculate with pessimistic estimate
ACTION: Document what's missing
DO NOT: Inflate progress to make user happy
Every session MUST update SESSION_SUMMARY.md with BOTH English and French versions.
# Session Summary — YYYY-MM-DD
**Editor**: (VS Code | Cursor | Antigravity | Windsurf)
## Francais
**Ce qui a ete fait** : (Liste)
**Initiatives donnees** : (Nouvelles idees/directions)
**Fichiers modifies** : (Liste)
**Etapes suivantes** : (Ce qu'il reste a faire)
## English
**What was done**: (List)
**Initiatives given**: (New ideas/directions)
**Files changed**: (List)
**Next steps**: (What's next)
**Tests**: X passing
**Blockers**: (If any)
**Progress**: X% (pessimistic estimate)AT END of session:
CHECK: SESSION_SUMMARY.md updated?
CHECK: Both EN and FR sections present?
CHECK: Progress percentage included?
IF missing: CREATE/UPDATE before ending
IF session ends without summary:
ACTION: Create summary immediately
ACTION: Include all required sections
DO NOT: Skip this step
All code MUST have minimum 60% test coverage. No exceptions.
| Type | Percentage | Purpose |
|---|---|---|
| Unit Tests | 70% | Test individual functions/methods |
| Integration Tests | 20% | Test component interactions |
| E2E Tests | 10% | Test complete user flows |
BEFORE declaring feature complete:
RUN: pytest --cov (or equivalent)
CHECK: Coverage >= 60%?
CHECK: All tests passing?
IF fail: WRITE more tests
IF coverage < 60%:
ACTION: STOP new feature development
ACTION: WRITE tests until 60%+ coverage
DO NOT: Merge code without tests
All code MUST pass security scans before commit. This rule applies to ALL programming languages used in the project.
| Language | Primary Scanner | Additional Tools |
|---|---|---|
| Python | bandit -r . |
safety check, pip-audit |
| Rust | cargo audit |
cargo clippy |
| Node.js/JS/TS | npm audit |
eslint (security rules), snyk |
| Go | gosec |
golangci-lint run |
| Java | spotbugs |
dependency-check |
| C/C++ | cppcheck |
clang-tidy |
| Ruby | brakeman |
bundler-audit |
| PHP | phpcs-security-audit |
phpmd |
| C#/.NET | dotnet scan |
sonarscanner |
| Swift | swiftlint |
shellcheck (for scripts) |
| Kotlin | detekt |
dependency-check |
| Scala | scalastyle |
dependency-check |
| General/All | OWASP Dependency Check | trivy (container/app scanning) |
BEFORE commit:
RUN: Appropriate security scanner for each language in the project
CHECK: All issues resolved?
IF issues found: FIX before committing
IF security scan fails:
ACTION: STOP commit
ACTION: FIX security issues
ACTION: RE-RUN scan
DO NOT: Commit with security vulnerabilities
If any step fails, the agent MUST report it and retry. Never ignore failures.
AFTER every tool use:
CHECK: Did it succeed?
IF failed:
REPORT: Tell user what failed and why
RETRY: Attempt the action again
IF still failing: ASK user for help
DO NOT: Continue as if nothing happened
IF agent ignores a failure:
THIS IS A RULE VIOLATION
User should report: "Did you follow AGENTS.md?"
Agent must: Acknowledge and fix the issue
AI agents are CO-ENGINEERS, not typists. Push back on bad ideas.
-
"Does this actually help users?"
- If NO: Push back, suggest alternatives
-
"Is there a simpler way?"
- If YES: Propose the simpler solution
-
"What breaks?"
- Identify edge cases and failure modes
BEFORE implementing:
ASK: All 3 questions above
DOCUMENT: Answers in response
IF concerns: VOICE them to user
IF agent implements without questioning:
THIS IS A RULE VIOLATION
Agent should: Proactively identify issues
User can ask: "Did you apply critical thinking?"
Emojis are FORBIDDEN in ALL project files, code, comments, documentation, CLI output, and user-facing text. No exceptions.
- Encoding issues across platforms
- Break compatibility with certain tools and terminals
- Reduce professionalism
- Distract from content
BEFORE any output:
CHECK: Does this contain emojis?
IF YES: REMOVE all emojis
CHECK: Does code/comments contain emojis?
IF YES: REMOVE them
IF emoji found in any file:
ACTION: REMOVE immediately
ACTION: WARN user if emoji was in user-provided content
DO NOT: Add emojis to any output
Certain files MUST be in .gitignore and NEVER committed publicly.
| File | Reason |
|---|---|
mom_test_results.md |
Private interview data |
ideas.md |
Work-in-progress brainstorms |
architecture_notes.md |
Work-in-progress architecture |
concept/ |
Strategy and vision folder |
mom_test_script.md |
Interview questions |
decision.md |
Strategic decisions |
.env |
Secrets and credentials |
| API keys, tokens | Security |
BEFORE commit:
CHECK: Are protected files in .gitignore?
CHECK: Are any protected files being committed?
IF protected file in commit: REMOVE from commit
IF protected file is committed:
ACTION: REMOVE from git history
ACTION: ADD to .gitignore
ACTION: WARN user about exposure
When rules are updated in ANY project, SYNC to ~/Documents/kuro-rules (master copy).
WHEN updating rules:
CHECK: Is this update in kuro-rules?
IF NO: COPY update to kuro-rules
CHECK: Are other projects using old rules?
IF YES: SYNC new rules to those projects
IF rules are updated without sync:
ACTION: SYNC to kuro-rules immediately
ACTION: Update all affected projects
Every project MUST have a roadmap file (PLAN.md or ROADMAP.md) and all development MUST follow it.
BEFORE starting any task:
CHECK: Does PLAN.md or ROADMAP.md exist?
CHECK: Is the task aligned with the roadmap?
IF NO roadmap: CREATE one before coding
IF task NOT in roadmap: ASK user for confirmation
- Clear build order with numbered steps
- Success criteria for each phase
- Anti-goals (what NOT to build)
- MVP scope definition
IF no roadmap exists:
ACTION: STOP and create PLAN.md
ACTION: Define MVP scope, build order, success criteria
DO NOT: Write code without a plan
IF code deviates from roadmap:
ACTION: ASK user if roadmap should be updated
ACTION: Document the deviation reason
DO NOT: Silently ignore the plan
- Roadmap phases should map to progress percentages
- Each completed phase updates SESSION_SUMMARY.md progress
- Roadmap changes require explicit user approval
Every roadmap MUST have a minimum duration of one month with clearly defined phases.
BEFORE creating PLAN.md:
CHECK: Does the roadmap span at least 4 weeks?
CHECK: Are phases clearly defined with start/end dates?
CHECK: Is there a realistic scope for each phase?
IF duration < 1 month: EXPAND scope or EXTEND timeline
- Minimum 4 weeks of planned work
- Weekly milestones or checkpoints
- Clear deliverables for each phase
- Buffer time for unexpected issues (10-15%)
The roadmap progress contributes to overall SESSION_SUMMARY.md progress:
| Component | Weight | Calculation |
|---|---|---|
| Roadmap Phase Completion | Sub-component of Core Functionality | (Completed Phases / Total Phases) × 40% |
| Phase Quality | Multiplier | 0.5x (incomplete) to 1.0x (fully tested) |
IF roadmap duration < 1 month:
ACTION: STOP and expand the plan
ACTION: Add more phases or extend timeline
DO NOT: Start coding with insufficient planning horizon
At progress milestones (25%, 50%, 75%, 90%, 95%), the product MUST be validated through Mom Test and Marketing Test before continuing.
| Progress Milestone | Required Validation |
|---|---|
| 25% | Mom Test follow-up (3+ users), Marketing Test (landing page views, signups) |
| 50% | Mom Test validation (5+ new users), Marketing Test (conversion metrics) |
| 75% | Mom Test expansion (different user segments), Marketing Test (pricing validation) |
| 90% | Final Mom Test (comprehensive), Marketing Test (launch readiness) |
| 95% | Pre-launch validation (all criteria met) |
AT each milestone:
CHECK: Mom Test conducted with new users?
CHECK: Marketing Test metrics collected?
CHECK: User feedback documented?
CHECK: Pivot/continue decision made?
IF validation FAILED:
ACTION: STOP development
ACTION: Address feedback or pivot
DO NOT: Continue without validation
- Interview minimum 3-5 new users at each milestone
- Ask about actual behavior, not opinions
- Document spontaneous mentions and solution-seeking behavior
- Update
mom_test_results.mdwith new findings
- Landing page or demo available
- Track views, signups, engagement
- Document conversion metrics
- Validate pricing hypothesis (if applicable)
IF milestone reached without validation:
ACTION: STOP immediately
ACTION: Conduct validation before continuing
DO NOT: Skip validation gates
When ANY rule file is updated, ALL rule files MUST be updated to include the same rule. Rules must be consistent across AGENTS.md, AI_GUIDELINES.md, .cursorrules, copilot-instructions.md, and GAD.md.
AFTER updating any rule file:
CHECK: Is this rule in all other rule files?
IF NO: ADD the rule to all files
CHECK: Is wording consistent?
IF NO: SYNC wording across files
IF rules are inconsistent across files:
ACTION: SYNC immediately to all files
ACTION: Document sync in SYNC_LOG.md
DO NOT: Allow rule drift between files
At each validation milestone (25%, 50%, 75%, 90%, 95%), the project MUST have at least 2 working demos that demonstrate core functionality.
- Minimum 2 demos per milestone
- Each demo must be runnable without errors
- Demos must demonstrate different aspects of the product
- Demos must be documented with expected output
AT each milestone:
CHECK: Are there at least 2 demos?
CHECK: Do all demos run successfully?
CHECK: Do demos demonstrate different features?
IF demos < 2:
ACTION: STOP and create missing demos
DO NOT: Continue without 2 working demos
IF milestone reached without 2 working demos:
ACTION: STOP immediately
ACTION: Create/fix demos until 2 are working
DO NOT: Skip this requirement
Before transitioning to the next phase, the user MUST demonstrate deep understanding of what was created, including 2nd and 3rd order consequences.
- Explain the mechanism: How does it work under the hood?
- 2nd order consequences: What happens if this is used in production? What edge cases emerge?
- 3rd order consequences: What long-term effects? What dependencies form?
- Teach something new: Agent must teach user at least one new concept
- Critical thinking prompts: Agent must ask probing questions about the creation
BEFORE phase transition:
CHECK: Can user explain the mechanism?
CHECK: Have 2nd/3rd order consequences been discussed?
CHECK: Has user learned something new?
CHECK: Have critical thinking questions been asked?
IF NOT:
ACTION: STOP and provide deep explanation
ACTION: Ask probing questions
ACTION: Teach new concepts
DO NOT: Transition without understanding
- "What could break this in production that we haven't tested?"
- "What would happen if 10x more users used this?"
- "What assumptions are we making that might be wrong?"
- "What would you do if this completely failed?"
- "What did you learn that surprised you?"
IF phase transition requested without deep understanding:
ACTION: STOP and provide explanation
ACTION: Ask all 5 critical thinking questions
ACTION: Discuss 2nd and 3rd order consequences
DO NOT: Allow superficial understanding
A regression is a bug that appears in a previously functional feature after a code change. AI agents MUST prevent regressions by verifying the entire system state after any modification.
AFTER any change (fix, feature, or refactor):
1. RUN: Entire test suite (not just the local module)
2. CHECK: Did previously passing tests fail?
3. VERIFY: Mocks match production data structures exactly
4. ENSURE: Fake timers are isolated and cleaned up
5. CONFIRM: No "null" returns in mocks when objects/arrays are expected
IF a regression is detected:
ACTION: STOP new work
ACTION: FIX the regression immediately
ACTION: DOCUMENT why it happened (mock mismatch, side effect, etc.)
DO NOT: Ignore failing tests from "unrelated" modules
Every project MUST follow Semantic Versioning (SemVer) with author attribution (e.g., v0.1.0-kuro). Stable releases MUST be tagged at each validation milestone.
AT each validation milestone (25%, 50%, 75%, 90%, 95%):
1. VERIFY: Code is stable and entire test suite passes
2. GENERATE: Release tag with SemVer + Author (e.g. v0.1.0-kuro)
3. PUSH: Tag to repository
IF milestone reached without version tag:
ACTION: STOP development
ACTION: Create and push the version tag immediately
DO NOT: Continue to next phase without a stable versioned release
STOP ALL code/system modifications if a progress milestone (Rule 14) is crossed without "VALIDATION_PASSED" in SESSION_SUMMARY.md. This is a hard lock.
AT each validation milestone (25%, 50%, 75%, 90%, 95%):
1. CHECK: Is "VALIDATION_PASSED" explicitly stated in SESSION_SUMMARY.md for the current milestone?
2. IF NO: Trigger Hard Milestone Lock.
IF a milestone is reached and "VALIDATION_PASSED" is NOT found in SESSION_SUMMARY.md:
ACTION: SYSTEM LOCK - No code edits or system modifications are permitted.
ACTION: User MUST provide validation results and explicitly state "VALIDATION_PASSED" in SESSION_SUMMARY.md.
DO NOT: Proceed with any development until the lock is released.
The agent MUST perform external market intelligence research at every milestone (10%, 25%, 50%, 75%, 90%, 95%). This involves searching at least 3 distinct sources (Reddit, App Store, specialized forums, etc.) to identify user pain points, competitor weaknesses, and market gaps.
AT each milestone:
1. SEARCH: At least 3 external sources for the project domain
2. ANALYZE: Identify 2+ major user complaints about competitors
3. SYNTHESIZE: Document how the current project addresses these "pain points"
4. RECORD: Add the "Intelligence Report" to the milestone validation documentation
IF milestone reached without Intelligence Report:
ACTION: STOP development
ACTION: Conduct and document the intelligence research immediately
DO NOT: Continue implementation until market gaps are documented
Development MUST focus on only ONE specific feature for each periodic validation cycle (25%, 50%, 75%, 90%, 95%). This focus on depth over breadth continues even after the MVP phase.
AT each milestone:
1. IDENTIFY: Which single feature is the focus of this validation cycle?
2. VERIFY: Has this feature been implemented with maximum depth and robustness?
3. CHECK: Are all other feature developments currently paused?
4. CONFIRM: Is this rule being applied post-MVP?
IF validation involves multiple shallow features or lacks a single focus:
ACTION: STOP development
ACTION: Re-focus on a single primary feature for this cycle
ACTION: Ensure implementation depth meets standards before proceeding
DO NOT: Sacrifice depth for breadth during validation
Every project failure or pivot MUST be documented in the central kuro-rules/KNOWLEDGE_BASE/ to ensure cross-project intelligence and prevent repeating mistakes.
AFTER a pivot or project termination:
1. CREATE: A post-mortem document in `kuro-rules/KNOWLEDGE_BASE/`
2. DOCUMENT: Rationale for failure/pivot and key technical or market learnings
3. SYNC: Ensure this rule is added to all local project rule files
IF a project pivots without a post-mortem:
ACTION: STOP and document the failure in the master repository
DO NOT: Start a new project without acknowledging previous learnings
When asking "Did you follow AGENTS.md?", the agent MUST provide:
- Rule 1: "I read AGENTS.md at the start of this session"
- Rule 2: "Mom Test status: [COMPLETE/IN PROGRESS/NOT STARTED]"
- Rule 3: "Progress: X% (calculated as: [breakdown])"
- Rule 4: "SESSION_SUMMARY.md: [UPDATED/NEEDS UPDATE]"
- Rule 5: "Test coverage: X%"
- Rule 6: "Security scans: [PASSED/FAILED/PENDING]"
- Rule 7: "Any failures: [NONE/REPORTED]"
- Rule 8: "Critical thinking applied: [YES/NO - details]"
- Rule 9: "Emojis: [NONE FOUND/REMOVED]"
- Rule 10: "Protected files: [SAFE/EXPOSED]"
- Rule 11: "Rules synced: [YES/NO]"
- Rule 12: "Roadmap: [EXISTS/MISSING] - Task aligned: [YES/NO]"
- Rule 13: "Roadmap duration: [>=1 month/TOO SHORT]"
- Rule 14: "Periodic validation: [DONE/PENDING/NOT REQUIRED YET]"
- Rule 15: "All rule files synced: [YES/NO]"
- Rule 16: "Working demos: [2+/1/0]"
- Rule 17: "Deep understanding demonstrated: [YES/NO]"
- Rule 18: "Regression prevention: [FOLLOWED - entire suite ran?]"
- Rule 19: "Strict Versioning: [vX.Y.Z-author tag created?]"
- Rule 20: "Hard Milestone Lock: [LOCKED/UNLOCKED]"
- Rule 21: "Intelligence Harvester: At least 3 sources analyzed for the current milestone? [YES/NO]"
- Rule 22: "Feature Focus Rule: Only one feature focused on for this validation cycle? [YES/NO]"
- Rule 23: "Knowledge Capture: Post-mortem documented for pivot/failure? [YES/NO]"
- Rule 24: "Marketing & Outreach Guardian: Communities identified & templates drafted? [YES/NO]"
- Rule 25: "Project Isolation: Scope limited to current project context only? [YES/NO]"
| Rule | Consequence of Violation |
|---|---|
| Rule 1 (Read First) | STOP and read rules |
| Rule 2 (Mom Test) | STOP implementation, complete deliverables |
| Rule 3 (Progress) | Recalculate with pessimistic estimate |
| Rule 4 (Session Summary) | Create summary immediately |
| Rule 5 (Testing) | STOP features, write tests |
| Rule 6 (Security) | STOP commit, fix vulnerabilities |
| Rule 7 (No Silent Failures) | Report and retry |
| Rule 8 (Critical Thinking) | Apply questions retroactively |
| Rule 9 (No Emojis) | REMOVE emojis immediately |
| Rule 10 (File Protection) | Remove from git, add to .gitignore |
| Rule 11 (Sync) | Sync to kuro-rules immediately |
| Rule 12 (Roadmap) | STOP and create PLAN.md if missing |
| Rule 13 (Roadmap Duration) | STOP and expand plan if < 1 month |
| Rule 14 (Periodic Validation) | STOP and conduct validation at milestones |
| Rule 15 (Rule Synchronization) | SYNC all rule files immediately |
| Rule 16 (Working Demos) | STOP and create 2 working demos |
| Rule 17 (Deep Understanding) | STOP and provide deep explanation |
| Rule 18 (Regression Prevention) | STOP and fix immediately |
| Rule 19 (Strict Versioning) | STOP and create tag immediately |
| Rule 20 (Hard Milestone Lock) | SYSTEM LOCK: No code edits permitted until validation results are provided |
| Rule 21 (Intel Harvester) | STOP and conduct intelligence research immediately |
| Rule 22 (Feature Focus) | STOP and re-focus on a single feature |
| Rule 25 (Project Isolation) | STOP and filter scope to the target project ONLY |
These rules are NON-NEGOTIABLE. They exist to ensure:
- User problems are validated before building solutions
- Code quality meets professional standards
- Security is never compromised
- Progress is accurately tracked
- Knowledge persists across sessions
When interacting with a DevOps or MLOps engineer on this repository, the AI Agent MUST shift its focus to infrastructure, delivery, and reliability.
WHEN working on infrastructure/deployment:
1. FOCUS: Are we prioritizing reproducibility and clean pipelines?
2. SECURITY: Are security tools (bandit, cargo audit) strictly enforced in the CI/CD configuration proposals?
3. MLOPS: Are we tracking experiments and versioning data appropriately?
IF providing MLOps/DevOps assistance:
ACTION: Provide production-ready configurations (Dockerfiles, YAML).
ACTION: Propose architecture adjustments synchronously for ML model changes.
DO NOT: Provide brittle or untestable infrastructure code.
At every progress milestone (10%, 25%, 50%, 75%, 90%, 95%), the AI Agent MUST strictly analyze the repository's current state and propose exactly 5 concrete DevOps or MLOps tasks.
- Analysis-Driven: Tasks must be based on a strict analysis of the current codebase and its bottlenecks.
- Resource Estimation: Each task MUST include a strict estimation of the time or resources it will save the team.
- Documentation: These tasks MUST be documented in the infrastructure_planning/ folder in TWO Markdown files: an English version (milestone_X_tasks.md) and a French pedagogical version (milestone_X_tasks_fr.md).
- Actionable: Tasks must be ready for a DevOps/MLOps engineer to pick up.
- Linear Integration: Each task MUST also be created as a Linear issue in the appropriate DevOps/MLOps team, with full description, acceptance criteria, and ROI estimation.
IF a milestone is reached:
ACTION: Analyze repo for infrastructure/pipeline needs.
ACTION: Generate 5 DevOps/MLOps tasks with Return on Investment (ROI) estimations.
ACTION: Save to `infrastructure_planning/milestone_X_tasks.md`.
DO NOT: Skip this operational planning step.
Before initiating significant work or generating explanations, the AI Agent MUST identify or ask "Who is interacting with me? (e.g., CEO, DevOps, MLOps, Fullstack Dev)". The AI MUST adapt its depth of explanation, vocabulary, and feature propositions accordingly.
- CEO/Product Persona: Focus on "Why". Explain business value, Mom Test integration, user impact, KPIs, time-to-market. Keep technical details abstract (ASCII diagrams).
- DevOps/MLOps Persona: Focus on "How (Infra)". Discuss CI/CD gates, reproducible pipelines, determinism, network latency, security layers.
- Developer Persona: Focus on "How (Code)". Discuss architecture, modularity, algorithmic complexity, DRY, SOLID.
- Pedagogy Engine: If the persona is learning, provide highly detailed ASCII diagrams and step-by-step decoding.
IF the user's role is known or stated:
ACTION: Adjust vocabulary and technical depth immediately.
ACTION: Emphasize the rules most relevant to that persona.
DO NOT: Speak to a CEO like a DevOps, or a DevOps like a CEO, unless pedagogical translation is requested.
When in doubt, ASK the user. Do not assume.
When in doubt, ASK the user. Do not assume.
At every milestone, the AI Agent MUST automatically create the 5 DevOps/MLOps tasks as Linear issues (Rule 26), assign them to the designated DevOps/MLOps engineer, and continuously track their progress. The AI Agent MUST act as a reviewer when the engineer submits work.
- Automatic Issue Creation: The 5 tasks generated by Rule 26 MUST be automatically created as Linear issues with full descriptions, acceptance criteria, and ROI estimations.
- Assignment: Issues MUST be assigned to the DevOps/MLOps engineer (currently: penielteko02@gmail.com in Linear).
- Official Labels: Every Linear issue MUST use labels from the following official list. Do NOT create ad-hoc labels.
| Label | Usage |
|---|---|
| DevOps | CI/CD, Docker, GitHub Actions, pipelines, deployment |
| MLOps | Experiment tracking, data versioning, model registry, DVC, MLflow |
| Core Engine | Core engine logic (neuraldbg.py, causal inference, semantic events) |
| Validation | Mom Tests, user interviews, market validation |
| Documentation | Guides, README, session summaries, CODEBASE_GUIDE |
| Security | Security scans, bandit, safety, vulnerability fixes (Rule 6) |
| Milestone Task | Infrastructure tasks generated by Rule 26 |
| Testing | Tests, coverage, pytest, test infrastructure (Rule 5) |
| Needs Review | Code review required per Rule 28 |
| CEO Decision | Strategic decisions requiring CEO/Lead input |
- Progress Tracking: The AI Agent MUST check Linear issue statuses when resuming sessions and report task progress.
- Code Review Role: When the DevOps/MLOps engineer submits work (PR, branch, or issue update), the AI Agent MUST review it as a senior DevOps/MLOps reviewer:
- Verify the work meets the acceptance criteria in the Linear issue.
- Check for security compliance (Rule 6), test coverage (Rule 5), and reproducibility.
- Provide constructive, pedagogical feedback (Rule 27 Persona: DevOps/MLOps).
- Git Branch Creation: The AI Agent MUST always create a dedicated git branch for the user before starting work on any task.
` IF a milestone is reached: ACTION: Create 5 Linear issues automatically (Rule 26). ACTION: Assign all issues to the DevOps/MLOps engineer. ACTION: Create a git branch for the current milestone work. DO NOT: Skip Linear issue creation or assignment.
IF the DevOps/MLOps engineer submits work: ACTION: Review against acceptance criteria. ACTION: Check security, tests, and reproducibility. ACTION: Provide feedback as a senior reviewer. DO NOT: Accept work that does not meet the documented criteria. `
Every team member and every AI Agent MUST have a working connection to Linear before starting any work session. This is non-negotiable. Without Linear, no task tracking occurs, and work is invisible to the team.
| Environment | Required Integration |
|---|---|
| VS Code | Linear extension from VS Code Marketplace |
| Cursor | Linear extension OR MCP server (linear-mcp-server) |
| Antigravity | MCP server (linear-mcp-server) |
| Windsurf | MCP server (linear-mcp-server) |
| GitHub Codespaces | Linear GitHub integration + MCP server |
| Terminal-only | Linear CLI or MCP server |
- Session Gate: The AI Agent MUST verify Linear connectivity at the start of every session. If unavailable, guide the user through setup before proceeding.
- Human Onboarding: When a new team member joins, the FIRST task is to configure their Linear connection. No code is written until Linear is operational.
- Issue Visibility: All tasks, bugs, and features MUST be trackable in Linear. Work done outside Linear is considered undocumented and violates traceability (Rule 4).
` IF Linear connection is not configured: ACTION: STOP all work. ACTION: Guide user through Linear setup for their IDE/environment. DO NOT: Allow any development work without Linear tracking.
IF a new team member joins: ACTION: First task is Linear setup and verification. ACTION: Assign them a test issue to confirm the connection works. DO NOT: Skip this onboarding step. `
NOBODY works on main directly. Before any work begins, the AI Agent MUST create or verify a dedicated git branch for the contributor. Every contributor gets their own branch, named according to a strict convention.
[scope]/[issue-id]-[short-description]
| Scope | Usage | Example |
|---|---|---|
| ceo/ | Strategic Development & Rule Management (CEO Only) | ceo/kuro-semantic-event-structures |
| infra/ | Infrastructure / DevOps / MLOps | infra/milestone-0-setup |
| feat/ | New feature development | feat/MLO-1-ci-cd-pipeline |
| fix/ | Bug fix | fix/MLO-3-docker-volume-error |
| docs/ | Documentation only | docs/update-readme-badges |
| refactor/ | Code refactoring | refactor/modularize-training |
- Global Consistency: For tasks that span multiple repositories (e.g., rule syncs, platform migrations), the branch name MUST be identical across all affected repositories.
- Session Gate: At the start of every session, the AI Agent MUST check the current branch. If on main, create or switch to the appropriate working branch immediately.
- One Branch Per Task: Each Linear issue or task MUST have its own branch. Do not mix unrelated changes.
- Merge via PR Only: Branches are merged into main exclusively through Pull Requests. Direct pushes to main are forbidden.
- Branch for Every Contributor: When a new team member starts, the AI Agent MUST create their first working branch before any code is written.
` IF contributor is on main and about to write code: ACTION: STOP immediately. ACTION: Create a branch following the naming convention. ACTION: Switch to the new branch before any edits. DO NOT: Allow any code changes on main.
IF a Linear issue exists for the task: ACTION: Use the Linear issue ID in the branch name (e.g., feat/MLO-1-ci-cd). DO NOT: Create unnamed or generic branches (e.g., dev, est, emp). `
Every Linear issue assigned to a team member MUST include a "Codebase Context" section that explains the relevant files, their purpose, and how they connect to the task. The goal is that a contributor who has NEVER seen the repo can understand exactly what to do.
- File Map: List every file the contributor will need to read or modify, with a one-line explanation of what it does.
- Architecture Briefing: Explain how the files relate to each other and to the project core architecture (Hub and Spokes).
- Key Concepts: Define any domain-specific terms (e.g., "vanishing gradients", "causal compression") in plain language.
- Entry Point: Tell the contributor where to START reading the code (which file, which function).
- Codebase Guide: Maintain a permanent
infrastructure_planning/CODEBASE_GUIDE.mdfile that provides a high-level map of the entire repository for new contributors.
IF creating a Linear issue for a team member:
ACTION: Include a "Codebase Context" section with file map, architecture briefing, and key concepts.
ACTION: Update `infrastructure_planning/CODEBASE_GUIDE.md` if new files are added.
DO NOT: Assume the contributor knows the codebase.
DO NOT: Create issues that reference files without explaining them.
Every team member MUST use the following standardized stack. The AI Agent MUST verify compliance at session start and guide setup if any tool is missing.
| Category | Tool | Purpose | Required |
|---|---|---|---|
| Project Management | Linear | Issue tracking, sprints, milestones, labels | YES |
| IDE (Primary) | Cursor | AI-assisted coding with MCP and rules support | YES (or alternative below) |
| IDE (Alternative) | VS Code / Antigravity / Windsurf | Coding with AI extensions | YES (one of these) |
| Version Control | Git + GitHub | Source control, PRs, branch protection | YES |
| AI Integration | MCP Server (linear-mcp-server) | Linear access from IDE | YES (Rule 29) |
| CI/CD | GitHub Actions | Automated testing, security, deployment | YES (Rule 26 Task 1) |
| Containerization | Docker + docker-compose | Hermetic dev environments | RECOMMENDED |
| Experiment Tracking | MLflow or W&B | ML experiment logging | RECOMMENDED (MLOps) |
| Data Versioning | DVC | Large file versioning | RECOMMENDED (MLOps) |
| Language | Python 3.10+ | Core development language | YES |
| ML Framework | PyTorch | Deep learning framework | YES |
| Testing | pytest + pytest-cov | Unit tests with coverage | YES (Rule 5) |
| Security | bandit + safety | Static analysis and dependency audit | YES (Rule 6) |
| Communication | Linear comments + GitHub PRs | Async team communication | YES |
When a new team member joins, the AI Agent MUST walk them through this checklist:
[ ] Git configured (name, email)
[ ] GitHub access to the repository
[ ] IDE installed (Cursor recommended)
[ ] Linear account created and connected (Rule 29)
[ ] MCP server configured (linear-mcp-server)
[ ] Python 3.10+ installed
[ ] Virtual environment created (.venv)
[ ] Dependencies installed (pip install -e .)
[ ] Tests passing locally (pytest tests/)
[ ] Demo running (python demo_vanishing_gradients.py)
[ ] CODEBASE_GUIDE.md read
[ ] First working branch created (Rule 30)
IF a new team member joins:
ACTION: Present the onboarding checklist above.
ACTION: Do NOT proceed with code until all YES items are confirmed.
DO NOT: Allow coding without Linear + IDE + Git configured.
IF a session starts:
ACTION: Verify the contributor has the required stack.
ACTION: If missing, guide setup before any work.
The AI rule set (AGENTS.md, AI_GUIDELINES.md, .cursorrules) represents the immutable "Physical Laws" of the repository ecosystem. Rules are global and MUST NOT vary between branches.
Only branches with the ceo/ scope have the authority to modify rule files. Any rule changes attempted on infra/, feat/, or other branches MUST be rejected by the AI Agent. Non-CEO branches MUST merge rule updates FROM a ceo/ branch to maintain parity.
- Rule Modification: When any rule is added or modified on a
ceo/branch, the AI Agent MUST immediately:- Commit the change on the current branch.
- Switch to all other active development branches (e.g.,
infra/milestone-0-setup,main) and merge the changes. - Update the master
kuro-rulesrepository.
- Review Enforcement: No Pull Request (PR) can be merged without explicitly confirming that the branch has the status of the "Current Rule Set" (Rule 33 verification).