A provider-agnostic AI skill for building production-grade applications with zero infrastructure required.
Status:
0.1.0-beta.1This skill is being actively developed. Feedback and contributions are welcome! See VISION.md for the project's motivation and design principles. See the docs at: https://deepwiki.com/Ircbarros/devweaver-lite/1-devweaver-lite-overview
AI coding agents are capable but undisciplined by default. They forget earlier decisions mid-task, rely on stale training-time library snapshots, skip tests and security checks, and make silent architectural choices that create hidden debt.
DevWeaver-Lite is a single-file skill that turns your AI assistant into a structured engineering partner. It enforces a 10-phase workflow with two mandatory human checkpoints (CONFIRM before code is written, GIT GATE before anything is committed), retrieves live documentation via Context7 before every implementation, and applies a library of embedded standards (OWASP, naming conventions, test coverage) to every session.
Zero Docker. Zero databases. Zero self-hosted services. Copy one file, configure two HTTP endpoints, and every session runs the same disciplined process.
| Mode | When | What the agent does |
|---|---|---|
| SCRATCH | Starting a new product from zero | Defines architecture from standards, creates C4 diagrams and ADRs, then builds with full test and security coverage |
| IMPROVE | Adding features or fixing bugs to an existing codebase | Scopes only touched modules, runs CARE-Lite retrieval, presents a bounded change plan before writing code |
| REFACTOR | Full realignment of an existing project to current standards | Audits the codebase against standards, proposes a phased plan, gets approval before each phase |
| ARCHITECTURE | Reviewing or redesigning system structure | Generates C4 Level 1-3 diagrams and documents decisions as ADRs without touching implementation code |
Implementing a new feature: The agent scans the knowledge catalog, retrieves live library docs via Context7, presents a C4 architecture diagram, waits for CONFIRM approval, then builds with tests:
Refactoring an existing project: The agent explores the structure, reads the devweaver-lite standards, validates the current architecture, reviews for code smells and security issues, then produces a scoped refactor plan with tests:
Running the VALIDATE phase: The agent executes the test suite, runs bandit and pip-audit security scans, and presents the full results before the GIT GATE:
Other things you can ask DevWeaver-Lite to do:
- Build a new API from scratch (FastAPI, Pydantic, OpenAPI docs) following the naming and module structure standards;
- Add a Svelte or SvelteKit frontend to an existing Python backend;
- Review an existing codebase for OWASP LLM Top 10 vulnerabilities;
- Improve test coverage to the 80% threshold on a legacy module;
- Generate a full C4 architecture diagram set (Level 1, 2, 3) for a system you need to document or present;
- Resume a partially finished feature from a known plan phase (CONTINUE mode);
- Migrate a monolith module into a bounded, independently testable structure;
- Audit and pin all dependency versions before a production release;
- Set up Playwright E2E tests for any user-facing flow;
- Write an ADR for a technology or architecture decision you have already made.
Every task runs the same sequence regardless of mode or provider:
sequenceDiagram
autonumber
actor Dev as Developer
participant Skill as DevWeaver-Lite Skill
participant Lib as Markdown Librarian
participant MCP as MCP Layer
participant Proj as Target Project
Dev->>+Skill: Describe task and provide project_root
Note over Skill: Phase 1 - PRE-TASK
Skill->>Dev: Confirm scope, constraints, acceptance criteria
Dev-->>Skill: Scope confirmed
Note over Skill: Phase 2 - REQUIREMENTS
Skill->>Skill: Extract functional and non-functional requirements
Skill->>Dev: Present structured requirements draft
Dev-->>Skill: Requirements approved
Note over Skill: Phase 3 - FETCH_RULES
Skill->>+Lib: CATALOG scan - keyword match on domain and task type
Lib-->>-Skill: Matched rule file paths (tier 1 candidates)
Skill->>+MCP: Context7 - fetch library and framework docs (tier 2)
MCP-->>-Skill: Official library documentation
Note over Skill: Phase 4 - RESEARCH
Skill->>+MCP: GitHub MCP - read existing codebase patterns
MCP-->>-Skill: Existing code context and conventions
Skill->>Skill: Synthesize rules, docs, and codebase into working context
Note over Skill: Phase 5 - ARCHITECTURE
Skill->>Skill: Produce C4 Level 2 container + sequence diagrams
Skill->>Skill: Produce implementation plan (phased, test-first)
Skill->>Dev: Present architecture proposal and plan
rect rgb(255, 245, 180)
Note over Skill,Dev: CONFIRM gate - human approval required
Skill-->>Dev: Deliverables: requirements + architecture + plan
alt Developer approves
Dev->>Skill: Approve
else Developer requests changes
Dev->>Skill: Return feedback
Skill->>Skill: Revise proposal
Skill->>Dev: Re-present revised deliverables
end
end
Note over Skill: Phase 6 - IMPLEMENT
Skill->>+Proj: Write tests first (TDD), then implementation
Proj-->>-Skill: Files written and staged
Note over Skill: Phase 7 - VALIDATE
Skill->>+Proj: Run tests, linter, type-checker, security scan
Proj-->>-Skill: Validation results
alt All checks pass
Skill->>Dev: Present validation summary
else Checks failing
Skill->>Skill: Fix failures and re-validate
end
rect rgb(255, 245, 180)
Note over Skill,Dev: GIT GATE - human approval required before commit
Skill-->>Dev: Staged diff and test results
alt Developer approves
Dev->>Skill: Approve commit
Skill->>+MCP: GitHub MCP - commit and push to branch
MCP-->>-Skill: Commit SHA confirmed
else Developer requests amendments
Dev->>Skill: Return amendment request
Skill->>Skill: Apply amendments
end
end
Note over Skill: Phase 8 - POST-TASK
Skill->>Skill: 6-step sweep: docs update, README, ADR, CATALOG, templates, CHANGELOG
Skill-->>-Dev: Task complete - summary and next steps
| Phase | What happens |
|---|---|
| PRE-TASK | Confirms mode (SCRATCH / IMPROVE / REFACTOR / ARCHITECTURE), scans CATALOG.md, sets context budget |
| REQUIREMENTS | Gathers and clarifies task scope with the developer |
| FETCH_RULES | Loads the 3 most relevant standards files (max 3 per phase per R-PD-03) |
| RESEARCH | CARE-Lite chain: CATALOG scan, Context7 live docs, web search, model knowledge fallback |
| ARCHITECTURE | Designs bounded modules, creates C4 diagrams, documents decisions as ADRs |
| CONFIRM gate | Presents full architecture to developer (waits for explicit approval before any code is written) |
| IMPLEMENT | Writes code, tests, and documentation per the confirmed architecture |
| VALIDATE | Runs tests, bandit security scan, pip-audit, Playwright E2E |
| GIT GATE | Presents the full diff (waits for explicit approval before any commit or PR) |
| POST-TASK | 6-step sweep: architecture sync, issue log, docs update, task close |
Neither gate can be bypassed. The agent cannot write code before CONFIRM or commit before GIT GATE, regardless of how the request is phrased.
- Node.js >= 18 (only required if using Playwright or Filesystem MCP -- optional)
- No other prerequisites for basic use
Step 1: Pick your provider from the table below and copy its activation file to the correct location.
Step 2 (For IDE providers only): Copy the MCP config template to your project.
Step 3: Tell the agent your project path if using a chat or web provider. (For IDE providers the workspace path should be detected automatically)
| Provider | Activation file | MCP config | Project path |
|---|---|---|---|
| GitHub Copilot | Copy provider-specific/copilot/.github/copilot-instructions.md to .github/ |
Merge provider-specific/copilot/.vscode/mcp.json into .vscode/ |
${workspaceFolder} implicit |
| Cursor | Copy provider-specific/cursor/.cursorrules to project root |
Merge provider-specific/cursor/.cursor/mcp.json into .cursor/ |
Workspace implicit |
| Windsurf | Copy provider-specific/windsurf/.windsurfrules to project root |
Merge provider-specific/windsurf/.windsurf/mcp.json into .windsurf/ |
Workspace implicit |
| Claude (claude.ai) | Upload provider-specific/claude/CLAUDE.md as Project Instructions; upload SKILL.md + librarian/CATALOG.md as Knowledge |
None needed | Tell agent in chat |
| Claude Desktop | Upload provider-specific/claude/CLAUDE.md; see claude_desktop_config.json.example |
See claude_desktop_config.json.example |
Tell agent in chat |
| Gemini (AI Studio) | Paste provider-specific/gemini/gemini_context.md as System Instructions |
None | Tell agent in chat |
| OpenAI (ChatGPT) | Paste provider-specific/openai/openai_context.md as Custom Instructions |
None | Tell agent in chat |
| OpenRouter | Paste provider-specific/openrouter/openrouter_context.md as system message |
None | Tell agent in chat |
| Kimi (Moonshot) | Paste provider-specific/kimi/kimi_context.md as system message |
None | Tell agent in chat |
| Mistral (Le Chat) | Paste provider-specific/mistral/mistral_context.md as system message |
None | Tell agent in chat |
| OpenClaw | Paste provider-specific/openclaw/openclaw_context.md as system message |
None | Tell agent in chat |
| Any other | See provider-specific/generic/README.md |
See provider-specific/generic/README.md |
Tell agent in chat |
For LangChain, AutoGen, CrewAI, Agno, Dify, or any OpenAI-compatible API,
inject the contents of SYSTEM_PROMPT.md as the system message.
| Framework | Injection method |
|---|---|
| LangChain | SystemMessage(content=open("SYSTEM_PROMPT.md").read()) |
| AutoGen | AssistantAgent(system_message=open("SYSTEM_PROMPT.md").read()) |
| CrewAI | Agent(backstory=open("SYSTEM_PROMPT.md").read()) |
| Dify / Flowise | Paste into the System Prompt field |
| OpenAI API | messages=[{"role":"system","content": ...}] |
| Agno | Agent(instructions=open("SYSTEM_PROMPT.md").read()) |
| MCP | Copilot | Cursor / Windsurf | Claude Desktop | Web providers |
|---|---|---|---|---|
| GitHub | HTTP (native Copilot, no token) | stdio binary + GITHUB_TOKEN |
stdio binary + GITHUB_TOKEN |
N/A |
| Context7 | HTTP (no install) | HTTP (no install) | npx -y mcp-remote |
N/A |
| Playwright | npx -y (optional) |
npx -y (optional) |
npx -y (optional) |
N/A |
| Filesystem | npx -y (optional, L3 refs) |
npx -y (optional, L3 refs) |
npx -y (optional) |
N/A |
Detailed MCP config templates are in each provider package.
For VS Code Copilot, GitHub and Context7 are HTTP -- zero install.
npx -y packages auto-download on first use -- no prior npm install needed.
For IDE providers (Copilot, Cursor, Windsurf): the agent uses the workspace path automatically.
For chat and API providers (Claude, Gemini, OpenAI, OpenRouter, Kimi, Mistral, OpenClaw), tell the agent at the start of each session:
Work on the project at /path/to/my-project
The agent will ask if it cannot determine the path.
| Feature | DevWeaver-Lite | Full DevWeaver |
|---|---|---|
| Setup time | 5 minutes | 30-60 minutes |
| Infrastructure | None required | Docker + 6 services |
| Knowledge retrieval | Markdown CATALOG (keyword) | Qdrant hybrid search (semantic) |
| Observability | None (stdout) | LangFuse traces |
| Session memory | Memory MCP (optional) | mem0ai (persistent) |
| Workflow | 10-phase behavioral | 10-phase LangGraph |
| Human gates | Provider tool approval | LangGraph interrupt_before |
| Standards/references | Identical (14 + 35 files) | Identical (14 + 35 files) |
| OWASP compliance | Full | Full |
- Skill does not activate: confirm you copied the correct activation file and placed it correctly (see Provider Setup table).
- MCP connection fails: confirm
GITHUB_TOKENis set for Cursor, Windsurf, or Claude Desktop. VS Code Copilot does not require a token. - Context budget warning: reduce L3 file loading to max 3 per phase (R-PD-03).
- CONFIRM gate not firing: review the provider-specific activation file -- ensure the full skill definition is present.
For edge-case documentation see references/teaching/guide_qa_simulation.md.
Have you used this skill on a real project? Share your results with the community.
Open a post in GitHub Discussions -- Show and Tell and include what you built, which provider you used, and what the agent produced.
Projects shared there may be featured in future documentation.
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
- Browse good first issues to get started
- Report bugs using the Bug Report template
- Request features using the Feature Request template
See SECURITY.md for the security policy and responsible disclosure process. Do not open public issues for security vulnerabilities.
MIT - Copyright (c) 2026 Italo Barros
If DevWeaver-Lite saves you time, consider buying me a coffee:
