bainary-skill

Files (29)

• ci.yml · .github/workflows/
• CHANGELOG.md
• LICENSE
• README.md
• SKILL.md
• CONVENTIONS.md · adapters/aider/
• CLAUDE.md · adapters/claude/
• AGENTS.md · adapters/codex/
• .cursorrules · adapters/cursor/
• CURSOR.md · adapters/cursor/
• AGENTS.md · adapters/grok/
• README.md · adapters/web-project/
• install.cmd
• install.ps1
• install.sh
• package.json
• bainary-skill · scripts/
• bainary-skill.ps1 · scripts/
• LICENSE · skills/pstack/
• README.md · skills/pstack/
• architecture.md · templates/.bainary/
• conventions.md · templates/.bainary/
• patterns.md · templates/.bainary/
• project-knowledge.md · templates/.bainary/
• session-handoff.md · templates/.bainary/
• .gitignore · templates/web-project/
• README.md · templates/web-project/
• package.json · templates/web-project/
• smoke.sh · tests/

SKILL.md (first lines)

# bainary-skill

Web Development Base Skill with Project Learning & Multi-CLI Support

## Overview

`bainary-skill` is a foundational skill for web development that combines the best practices from:

- **mattpocock/skills** — Composable, real engineering discipline
- **thananon/9arm-skills** — Practical structure and community usage
- **multica-ai/andrej-karpathy-skills** — Strong principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution)

**Key differentiators:**
- Actively learns and understands the target project before generating code
- Maintains updatable project knowledge over time
- Works across multiple AI CLIs (Claude Code, Cursor, Codex, Grok, Aider)

## When to Use

- Starting a new web project and want consistent architecture + principles
- Working on an existing web codebase and want the AI to respect its patterns
- Want to maintain long-term project context across multiple sessions
- Using multiple AI coding tools and want unified behavior

**Don't use for:**
- Non-web projects (mobile, CLI tools, embedded)
- One-off scripts with no architecture concerns

## Core Principles (Adapted from Karpathy)

1. **Think Before Coding** — Analyze requirements, data flow, and component boundaries before writing code.
2. **Simplicity First** — Prefer simple, maintainable solutions over clever abstractions.
3. **Surgical Changes** — Modify only what is necessary; avoid touching unrelated code.
4. **Goal-Driven Execution** — Every change should have a clear, verifiable goal (render correctly, pass tests, meet performance targets).

## Project Learning System

`bainary-skill` maintains a `.bainary/` directory inside each project:

```
.bainary/
├── project-knowledge.md      # Main knowledge file (start here)
├── session-handoff.md        # Latest AI chat summary, decisions, risks, next steps
├── architecture.md           # High-level architecture decisions
├── patterns.md               # Recurring patterns discovered
└── conventions.md            # Naming, folder structure, styling rules
```

Templates for these files are in `templates/.bainary/`.

### Optional pstack mode

This repository includes the standalone pstack Agent Skills under `skills/pstack/`.
They are disabled by default and can be enabled per project:

```bash
bainary-skill mode pstack
```

When enabled, use `skills/pstack/poteto-mode/SKILL.md` as the entry point for
rigorous non-trivial work. It routes to pstack playbooks and principles as
needed. Disable it with `bainary-skill mode normal`. pstack does not replace
Bainary's project-learning, security, validation, or data-loss rules.

### Optional `define-goal` skill

The repository also ships `skills/define-goal/SKILL.md` for tasks that need goal
clarification before execution. Use it only when goal definition is requested or
genuinely needed; do not force it onto ordinary implementation work.

### Continuity Loop

1. Start each new AI chat by reading all `.bainary/` files.
2. If `patterns.md` or `conventions.md` is generic, inspect source code first and update them with the project's real style/code patterns.
3. During work, record stable decisions and patterns in the appropriate `.bainary/` file.
4. Before ending a chat, update `session-handoff.md` so the next chat can continue.

### Automatic Project Learning

AI assistants using this skill must learn project changes proactively. Do not wait for the user to say "learn this" or "update handoff".

Before giving a final response for any meaningful coding, debugging, design, refactor, or documentation task:

1. Check whether `.bainary/session-handoff.md` exists.
2. If it exists, update it automatically with what changed in this session, files touched, decisions made, newly discovered project patterns, open tasks, next steps, and risks to verify.
3. If a newly discovered pattern is stable and likely reusable, also update the right durable knowledge file:
   - `.bainary/patterns.md` for code/component/API/testing patterns
   - `.bainary/conventions.md` for naming, folder, formatting, or workflow conventions
   - `.bainary/architecture.md` for architecture and data-flow decisions
   - `.bainary/project-knowledge.md` for tech stack, entry points, or project status
4. Mention briefly in the final response that the project handoff/knowledge was updated.

Do **not** record temporary noise: failed attempts already fixed, raw command output, transient errors, unrelated chat, secrets, tokens, or `.env` values.

### Learning Commands

| Command | Description |
|---------|-------------|
| `bainary-skill learn` | Perform initial project discovery and create knowledge base |
| `bainary-skill update` | Update CLI instruction files from latest skill version |
| `bainary-skill status` | Show current knowledge state and installed files |

### Installing the CLI

```bash
curl -sL https://raw.githubusercontent.com/BainaryTD/bainary-skill/main/scripts/bainary-skill \
  -o /usr/local/bin/bainary-skill && chmod +x /usr/local/bin/bainary-skill
```

## Multi-CLI Support

The skill exports compatible instruction files for different AI CLIs:

| CLI | File | Adapter |
|-----|------|---------|
| Claude Code | `CLAUDE.md` | `adapters/claude/` |
| Cursor | `.cursorrules` + `CURSOR.md` | `adapters/cursor/` |
| Codex | `AGENTS.md` | `adapters/codex/` |
| Grok | `AGENTS.md` | `adapters/grok/` |

From BainaryTD/bainary-skill, MIT.

More from BainaryTD/bainary-skill