🔧 DevContextForge

Deterministic AI context scaffolding for modern development environments.
Define the contract. Govern the AI.

---

What is DevContextForge?

AI-powered editors are powerful — but they're inconsistent without clear constraints. DevContextForge generates structured, role-driven AI development context for your repository so your AI tools follow a defined contract instead of guessing.

Think of it as ESLint for AI behavior — standardized, versionable, deterministic.

---

⚡ Quick Start

npx devcontextforge init

or with flags:

npx devcontextforge init --env cursor --role senior-developer --strict ultra

---

🤖 Supported Environments

Environment	Generated Files
Cursor	.cursorrules, .cursor/rules/devcontextforge.mdc, skills.md
VS Code / GitHub Copilot	.github/copilot-instructions.md, .github/skills/<role>/SKILL.md, .vscode/settings.json, .vscode/extensions.json, skills.md
Claude Code	CLAUDE.md, .claude/rules/code-style.md, .claude/rules/security.md, .claude/rules/testing.md, skills.md
Cloud IDE	.devcontainer/devcontainer.json, skills.md

---

👤 Role Profiles — Full Spectrum

Generalist Levels (Experience-Based)

Role	Level	Focus
🌱 Junior Developer	0–2 yrs	Learning fundamentals, mentorship-oriented AI
🚀 Mid-Level Developer	2–5 yrs	Independent feature ownership
⚡ Senior Developer	5–8 yrs	Production-grade, explicit error handling
🏗️ Staff Engineer	8–12 yrs	Cross-team impact, platform engineering
🎯 Principal Engineer	12+ yrs	Org-wide strategy, Conway's Law awareness

Specialized Roles

Role	Focus
🎨 Frontend Engineer	Accessibility (WCAG 2.1), Core Web Vitals, component-driven
⚙️ Backend Engineer	APIs, reliability, distributed systems, observability
🔄 Full Stack Engineer	End-to-end ownership, shared TypeScript types
🛠️ DevOps / Platform Engineer	IaC, GitOps, SRE, developer experience
📊 Data / ML Engineer	Data quality, ML lifecycle, pipeline engineering

Leadership Roles

Role	Focus
🧭 Tech Lead	Hands-on squad leadership, team standards
🏛️ Software Architect	ADRs, formal design reviews, cross-cutting concerns
👥 Engineering Manager	People, delivery, team health
🔒 Security / AppSec Engineer	Threat modeling, OWASP, shift-left security
✏️ Custom Role	Define your own with a free-text description

---

🎛 Strictness Levels

Level	Behavior
⚖️ Balanced	AI has creative freedom within role guidelines. Best for exploration.
📏 Strict	AI must justify deviations and follow standards rigorously.
🔒 Ultra	Maximum enforcement. Every output must be production-ready. Best for critical systems.

---

📁 Generated Output Examples

Cursor

skills.md          # Universal AI contract
.cursorrules       # Legacy Cursor rules (widely supported)
.cursor/
  rules/
    devcontextforge.mdc  # New .mdc format with YAML frontmatter

VS Code / GitHub Copilot

skills.md
.github/
  copilot-instructions.md     # Repository-level Copilot context
  skills/
    senior-developer/
      SKILL.md                # Agent Skill (agentskills.io spec)
.vscode/
  settings.json               # Workspace settings with Copilot config
  extensions.json             # Recommended extensions

Claude Code

skills.md
CLAUDE.md                     # Main project memory file
.claude/
  rules/
    code-style.md             # Path-scoped: src/**/*
    security.md               # Path-scoped: api/**/*
    testing.md                # Path-scoped: **/*.test.*

---

🧠 How It Works

1. Run devcontextforge init — interactive prompts guide you through environment, role, and strictness selection
2. Role profile is loaded — one of 14 built-in profiles (or your custom description)
3. Strictness modifier is applied — adds progressive AI contract rules
4. Templates are rendered — environment-specific files generated using your role + config
5. Files are written — commit to version control; AI tools apply the contract on every run

---

🛠 CLI Reference

devcontextforge init [options]

Options:
  --env <environment>    cursor | vscode | claude-code | cloud
  --role <role>          junior-developer | mid-developer | senior-developer |
                         staff-engineer | principal-engineer | frontend-engineer |
                         backend-engineer | fullstack-engineer | devops-engineer |
                         data-engineer | tech-lead | architect |
                         engineering-manager | security-analyst | custom
  --strict <level>       balanced | strict | ultra  (default: balanced)
  --dry-run              Preview files without writing
  --force                Overwrite existing files
  --cwd <path>           Target directory  (default: current directory)
  -v, --version          Show version
  -h, --help             Show help

---

📝 Example: skills.md Excerpt

# AI Development Context
# Role: ⚡ Senior Developer | Strictness: strict

## AI Operating Rules
- No speculative abstractions — implement what is needed today
- Explain architectural tradeoffs when multiple approaches exist
- Do not refactor without explicit justification of the benefit
- Flag any code that bypasses existing abstractions or patterns
- Require justification before refactoring existing code [strict]
- Enforce type annotations on all function signatures [strict]

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-role
3. Add your role JSON to roles/ following the schema
4. Submit a PR with clear description and tests

Contribution areas:

• New role profiles
• Additional IDE environment adapters
• Template improvements
• CLI enhancements

---

📄 License

MIT © DevContextForge Contributors

---

DevContextForge — AI tools should follow a contract, not guess.