🧠 nirvana-context-engineering

Context engineering squad for AI agents — a 5-phase pipeline that transforms raw requirements into optimized context artifacts: CLAUDE.md, contextual rules, AGENTS.md, memory configurations, and prompt templates.

📋 Table of Contents

• Overview
• Installation
• Pipeline
• Agents
• Tasks
• Workflows
• Context Engineering Approaches
• Best Practices 2026
• Generated Artifacts
• Usage
• Configuration
• Directory Structure
• Troubleshooting
• Contributing
• License

🔭 Overview

The nirvana-context-engineering squad addresses a critical problem in AI-agent-driven development: poorly structured context destroys output quality and inflates costs. Agents receiving generic, bloated, or disorganized context make poor decisions, ignore project constraints, and repeat already-documented mistakes.

This squad applies state-of-the-art Context Engineering practices to ensure each agent receives exactly the right context — no more, no less.

Who is this squad for?

• Teams adopting AIOS who need high-quality initial context setup
• Legacy projects being onboarded to agent-driven development
• Teams noticing progressive quality degradation in AI responses
• Engineers who want to standardize context management across multiple projects

⚡ Installation

npx squads add gutomec/squads-sh/nirvana-context-engineering

Verify installation:

squads list | grep nirvana-context-engineering

🔄 Pipeline

The squad executes a sequential 5-phase pipeline, from requirements gathering to final context optimization:

Pipeline phases:

🤖 Agents

📋 Tasks

.claude/rules/

🔀 Workflows

context_engineering_pipeline — Main Pipeline

Sequential 5-phase pipeline that executes the full flow from collection to optimization. Each phase depends on artifacts from the previous one. Recommended for new projects or initial onboarding of legacy projects.

context_optimization_cycle — Iterative Cycle

Optimization loop for projects with existing context that needs refinement. Analyzes current artifacts, identifies issues, and applies incremental improvements. Recommended for periodic maintenance and continuous improvement of already-established context.

/ce optimize

🧩 Context Engineering Approaches

The squad implements and combines five complementary context management approaches:

🏆 Best Practices 2026

.claude/rules/

📦 Generated Artifacts

The squad produces a complete set of context artifacts ready for immediate use:

• CLAUDE.md — Main context file (≤ 200 lines), containing general instructions, stack, conventions, and constraints

• .claude/rules/

  — Contextual rules with paths: frontmatter for selective loading by file scope
• AGENTS.md — Catalog of available agents with personas, capabilities, and activation examples
• Memory configs — Short-, medium-, and long-term memory configurations for context persistence
• Prompt templates — Reusable templates for common tasks with typed placeholders

💻 Usage

Main Commands

# Start the full pipeline (default flow)
/ce start

# Run project scanning only
/ce scan

# Optimize existing context
/ce optimize

# Validate quality of current artifacts
/ce validate

# Inspect the generated context architecture
/ce inspect

# Help and command list
/ce help

Full Flow Example

# 1. Install the squad
npx squads add gutomec/squads-sh/nirvana-context-engineering

# 2. Start the pipeline in the target project
cd my-project
/ce start

# 3. Answer the Interviewer's questions (interactive)
# The agent will ask about: stack, team, constraints, goals

# 4. Wait for the pipeline to complete (automatic after interview)

# 5. Review the generated artifacts
ls .claude/
cat CLAUDE.md

# 6. Commit the context artifacts
git add CLAUDE.md .claude/ AGENTS.md
git commit -m "feat: context engineering artifacts [ce-pipeline]"

Initial Setup — Checklist

• Squad Protocol v5 installed and configured
• Claude Code active in the project
• Squad installed via npx squads add
• Project directory with git initialized
• Write permission on

  .claude/

  and project root
• Pipeline executed with

  /ce start

• Artifacts reviewed and committed

⚙️ Configuration

name: nirvana-context-engineering
version: 1.0.0
slashPrefix: ce
protocol: "5.0"

settings:
  maxClaudeMdLines: 200
  compactionTarget: 0.5        # 50% token reduction
  language: en-US
  encoding: utf-8
  generateAgentsMd: true
  generateMemoryConfigs: true
  generatePromptTemplates: true

pipeline:
  workflow: context_engineering_pipeline
  phases:
    - agent: interviewer
      task: gatherRequirements
    - agent: scanner
      task: scanProject
    - agent: architect
      task: designContextArchitecture
    - agent: generator
      task: generateContextArtifacts
    - agent: optimizer
      task: optimizeContext

config/agents/

# config/agents/interviewer.yaml
interviewer:
  maxQuestions: 20
  requiredTopics:
    - stack
    - teamSize
    - codeConventions
    - ciCdPlatform
    - testingStrategy
  skipIfExists:
    - requirements.yaml

# Enable verbose mode in the pipeline
CE_VERBOSE=true

# Override artifact language
CE_LANGUAGE=en-US

# Disable prompt template generation
CE_SKIP_TEMPLATES=true

# Custom path for artifacts
CE_OUTPUT_DIR=.context/

📁 Directory Structure

squads/nirvana-context-engineering/
├── README.md                    # Portuguese version
├── README.en.md                 # This file
├── squad.yaml                   # Main configuration
├── component-registry.md        # Component registry
├── analysis.md                  # Design analysis
│
├── agents/
│   ├── interviewer.yaml         # 🎯 Interviewer agent
│   ├── scanner.yaml             # 🔬 Scanner agent
│   ├── architect.yaml           # 🏗️ Architect agent
│   ├── generator.yaml           # ⚡ Generator agent
│   └── optimizer.yaml           # 🔧 Optimizer agent
│
├── tasks/
│   ├── gather-requirements.yaml
│   ├── scan-project.yaml
│   ├── design-context-architecture.yaml
│   ├── generate-context-artifacts.yaml
│   ├── optimize-context.yaml
│   └── validate-context-quality.yaml
│
├── workflows/
│   ├── nirvana-context-engineering-pipeline.yaml
│   └── context-optimization-cycle.yaml
│
├── templates/
│   ├── claude-md.md             # Base template for CLAUDE.md
│   ├── agents-md.md             # Base template for AGENTS.md
│   ├── rule-template.md         # Template for contextual rules
│   └── memory-config.yaml       # Memory configuration template
│
├── checklists/
│   ├── quality-gate.md          # Final quality checklist
│   └── review-checklist.md      # Manual review checklist
│
├── config/
│   └── defaults.yaml            # Squad default settings
│
├── references/
│   ├── nirvana-context-engineering-guide.md
│   └── best-practices-2026.md
│
└── scripts/
    ├── validate.sh              # Local validation script
    └── metrics.sh               # Context metrics collection

🔧 Troubleshooting

.claude/rules/

.claude/rules/

ls -la .claude/

chmod 755 .claude/

/ce optimize

npx squads add --force gutomec/squads-sh/nirvana-context-engineering

🤝 Contributing

Contributions are welcome! Please follow the standard AIOS flow:

1. Create a story in

   docs/stories/

   describing the improvement
2. Implement following the Story Development Cycle (SDC)
3. Run the QA Gate with @qa
4. Submit via @devops with a descriptive PR

For discussions about squad architecture, open an issue with the nirvana-context-engineering label.

📄 License

Distributed under the MIT license. See LICENSE for full details.