nobrainer-starter

name

nobrainer-starter

description

Project starter - creates AGENTS.md and CLAUDE.md with identical NoBrainer engineering standards and workflow rules. Both files get the same content so the project works with Claude Code, Codex, Kimi, Cursor, or any AI coding assistant. Use when starting a new project or bootstrapping an existing one. Trigger on "setup project", "init project", "nobrainer-starter", "create AGENTS.md", "bootstrap project standards".

NoBrainer Project Starter

Bootstraps a project with engineering standards and workflow rules.

Both AGENTS.md and CLAUDE.md receive identical content so the project works correctly regardless of which AI coding assistant reads it (Claude Code, Codex, Kimi, Cursor, etc.).

Your Task

1. Check current working directory for existing AGENTS.md and CLAUDE.md
2. Write both files with the full content below — if a file already exists, merge intelligently (add only missing sections, never overwrite existing content)
3. Create tasks/ directory with stub files if not present

---

Full Content — Write to Both AGENTS.md and CLAUDE.md

# Engineering Standards & Workflow Rules

## Core Engineering Principles

- **DRY (Don't Repeat Yourself)** — eliminate code duplication.
- **KISS (Keep It Simple, Stupid)** — prefer simplicity and minimalism.
- **SOLID** — follow all five OOP principles for clean architecture.
- **YAGNI (You Ain't Gonna Need It)** — implement only what is required now.
- **Clean Code** — focus on readability, consistency, and maintainability.
- **Self-explanatory code** — names should describe purpose; comments only where necessary.
- **Separation of Concerns** — each class/module should have a single responsibility.
- **Encapsulation** — hide internal logic, expose only required interfaces.
- **Composition over Inheritance** — prefer modular composition for flexibility.
- **Fail Fast** — validate inputs early and handle errors explicitly.
- **Immutable Data** — avoid unintended state changes where possible.
- **Dependency Injection** — improve modularity and enable easy testing.
- **Convention over Configuration** — use predictable and consistent patterns.
- **Single Source of Truth** — avoid duplicating state or logic.
- **Code for humans, not machines** — readability is more important than brevity.
- **Testability** — design so code can be easily unit and integration tested.
- **Error Handling** — provide meaningful, user-safe error responses.
- **Logging and Monitoring Ready** — log key events with proper levels and context.
- **Performance Aware** — write efficient code without premature optimization.
- **Production Ready** — ensure stability, resilience, observability, and documentation.

## Structural and Design Recommendations

- Use POM (Page Object Model) or layered architecture to separate UI, logic, and data.
- Maintain clear naming conventions for variables, functions, and classes.
- Avoid magic numbers and hardcoded values — use constants or enums.
- Keep functions small and focused — each should perform one logical action.
- Don't comment bad code — rewrite it.
- Write once, read many — optimize for readability and long-term maintenance.
- Prefer explicitness over implicitness — avoid hidden behavior or side effects.
- Consistent formatting and indentation — follow language style guides.
- Meaningful structure — organize code into logical, reusable modules.

## Communication and Work Ethics

- **No Documentation Unless Explicitly Requested** — write self-documenting code. Only create docs, READMEs, or extensive comments when specifically asked.
- **Pareto Principle (80/20 Rule)** — focus on the 20% of features that deliver 80% of the value. Prioritize high-impact solutions.
- **Uncertainty Verification** — when uncertain about requirements or best practices, state it explicitly and ask before proceeding.
- **No Emoji Usage** — maintain professional communication without emojis in code, comments, or responses.
- **Single Method Approach** — use one proven method per problem. Avoid multiple fallback solutions unless explicitly asked for options.
- **Silent Best Practices** — apply engineering principles without announcing them in comments. Code demonstrates good practices through structure, not methodology commentary.

## General Expectations

- Output must be clean, consistent, and executable.
- Include minimal but clear comments where they add context.
- Avoid unnecessary libraries and dependencies.
- Always assume the code will go to production.
- Prioritize clarity, correctness, and maintainability over cleverness.
- Final output must be ready for real-world deployment with no major refactoring required.

## Implementation Guidelines

1. Start with the core functionality that delivers the most value.
2. Question assumptions and verify requirements when unclear.
3. Write code that explains itself through clear naming and structure.
4. Test critical paths but don't over-engineer test coverage initially.
5. Optimize for change by keeping components loosely coupled.
6. Document only when necessary — focus on why, not what.
7. Communicate uncertainties clearly and seek confirmation.
8. Deliver working solutions incrementally rather than waiting for perfection.

## Workflow Orchestration

### 1. Plan Mode Default
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately — don't keep pushing
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

### 2. Subagent Strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution

### 3. Self-Improvement Loop
- After ANY correction from the user: update `tasks/lessons.md` with the pattern
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review lessons at session start for relevant project

### 4. Verification Before Done
- Never mark a task complete without proving it works
- Diff behavior between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness

### 5. Demand Elegance (Balanced)
- For non-trivial changes: pause and ask "is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes — don't over-engineer
- Challenge your own work before presenting it

### 6. Autonomous Bug Fixing
- When given a bug report: just fix it. Don't ask for hand-holding
- Point at logs, errors, failing tests — then resolve them
- Zero context switching required from the user
- Go fix failing CI tests without being told how

## Task Management

1. **Plan First** — write plan to `tasks/todo.md` with checkable items
2. **Verify Plan** — check in before starting implementation
3. **Track Progress** — mark items complete as you go
4. **Explain Changes** — high-level summary at each step
5. **Document Results** — add review section to `tasks/todo.md`
6. **Capture Lessons** — update `tasks/lessons.md` after corrections

## Core Principles

- **Simplicity First** — make every change as simple as possible, impact minimal code
- **No Laziness** — find root causes, no temporary fixes, senior developer standards
- **Minimal Impact** — changes should only touch what's necessary, avoid introducing bugs

## Git Rules

- Never commit without explicit user approval per each commit
- Never commit directly to main/master — always use branches and PRs
- Create PR only when explicitly asked
- No large volumes of redundant versioned files — patch files in place

## Safety Rules

- **Never execute destructive commands without explicit user confirmation** — this includes: `rm -rf`, recursive deletion, `DROP TABLE`, `DELETE FROM` without WHERE, `git reset --hard`, `git push --force`, truncating files, wiping directories, killing critical processes
- Before any irreversible operation: state clearly what will be deleted/destroyed and ask for confirmation
- When in doubt whether an operation is destructive: ask first, act second
- Prefer reversible operations — move to trash instead of delete, backup before overwrite, branch before rebase

---

tasks/ Stub Files

Create tasks/ directory and the following files if they don't exist:

tasks/todo.md:

# TODO

## Current Task

- [ ] ...

## Completed

- [x] Project initialized with NoBrainer standards

tasks/lessons.md:

# Lessons Learned

## Format

Each entry: date, what went wrong, rule to prevent recurrence.

---

---

Merge Rules

• If a file already contains an equivalent section, skip it — don't duplicate
• Preserve all existing content — only ADD, never remove
• Place new sections at the END of existing files
• Keep existing file's style and language

After Writing

Confirm to user:

Project bootstrapped:

AGENTS.md — full standards (engineering + workflow + safety)
CLAUDE.md — full standards (engineering + workflow + safety)
tasks/todo.md — task tracker
tasks/lessons.md — lessons log