derolicia 1.0.0

package/docs/community/README-community-snippet-core.md

@@ -0,0 +1,57 @@
+# README Community Section - dera-core
+
+> 🌐 **EN** | [PT](../pt/community/README-community-snippet-core.md) | [ES](../es/community/README-community-snippet-core.md)
+
+> **Purpose:** Copy this snippet into the README.md of `dera-multiagents/dera-core` repository.
+
+---
+
+## 💬 Community & Discussions
+
+This repository hosts the **central community hub** for all Dera projects.
+
+👉 **[Join the Discussion](https://github.com/dera-multiagents/dera-core/discussions)**
+
+### Discussion Categories
+
+| Category               | Purpose                                                                  |
+| ---------------------- | ------------------------------------------------------------------------ |
+| 📣 **Announcements**   | Official updates and news from the Dera team                             |
+| 💬 **General**         | General discussions about Dera                                           |
+| 💡 **Ideas**           | Propose new features and improvements                                    |
+| 🙏 **Q&A**             | Ask questions and get help                                               |
+| 🙌 **Show and Tell**   | Share your projects built with Dera                                      |
+| 🐛 **Troubleshooting** | Get help with issues and problems                                        |
+| 📦 **Squads**          | Discussions about [Dera Squads](https://github.com/dera-multiagents/dera-squads) |
+| 🔧 **MCP Ecosystem**   | Discussions about [MCP tools](https://github.com/dera-multiagents/mcp-ecosystem) |
+
+### Quick Links
+
+| Action               | Link                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| 🐛 Report a bug      | [Open Issue](https://github.com/dera-multiagents/dera-core/issues/new?template=bug_report.md)               |
+| 💡 Request a feature | [Start Discussion](https://github.com/dera-multiagents/dera-core/discussions/new?category=ideas)            |
+| ❓ Ask a question    | [Q&A](https://github.com/dera-multiagents/dera-core/discussions/new?category=q-a)                           |
+| 📦 Propose a Squad   | [dera-squads issues](https://github.com/dera-multiagents/dera-squads/issues/new?template=squad-proposal.md) |
+| 🔧 MCP question      | [MCP Ecosystem](https://github.com/dera-multiagents/dera-core/discussions/new?category=mcp-ecosystem)       |
+
+### Related Repositories
+
+| Repository                                                 | Description                      | License        |
+| ---------------------------------------------------------- | -------------------------------- | -------------- |
+| [dera-core](https://github.com/dera-multiagents/dera-core)         | Core framework (you are here)    | MIT            |
+| [dera-squads](https://github.com/dera-multiagents/dera-squads)     | Dera Squads (ETL, Creator, MMOS) | MIT            |
+| [mcp-ecosystem](https://github.com/dera-multiagents/mcp-ecosystem) | Docker MCP Toolkit & IDE configs | Apache 2.0     |
+
+### Contributing
+
+We welcome contributions! Check out our:
+
+- 📖 [Contributing Guide](../../CONTRIBUTING.md)
+- 📜 [Code of Conduct](../../CODE_OF_CONDUCT.md)
+- 🏗️ [Coding Standards](../ARCHITECTURE/coding-standards.md)
+- 🏷️ [Good First Issues](https://github.com/dera-multiagents/dera-core/labels/good-first-issue)
+
+---
+
+**Tagline:** _Dera: AI-Orchestrated System for Full Stack Development_ 🚀

package/docs/community/README-community-snippet-mcp.md

@@ -0,0 +1,49 @@
+# README Community Section - mcp-ecosystem
+
+> 🌐 **EN** | [PT](../pt/community/README-community-snippet-mcp.md) | [ES](../es/community/README-community-snippet-mcp.md)
+
+> **Purpose:** Copy this snippet into the README.md of `dera-multiagents/mcp-ecosystem` repository.
+
+---
+
+## 💬 Community & Support
+
+For discussions, questions, and community interaction, visit our central hub:
+
+👉 **[Dera Community Discussions](https://github.com/dera-multiagents/dera-core/discussions)**
+
+| Need                         | Where to Go                                                                                                    |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| 🔧 **MCP questions?**        | Use the ["MCP Ecosystem" category](https://github.com/dera-multiagents/dera-core/discussions/categories/mcp-ecosystem) |
+| 💡 **Feature ideas?**        | Start a [Discussion in "Ideas"](https://github.com/dera-multiagents/dera-core/discussions/categories/ideas)            |
+| 🐛 **Found a bug?**          | [Open an issue](https://github.com/dera-multiagents/mcp-ecosystem/issues/new/choose) in **this repository**            |
+| 🙏 **Need help?**            | Ask in ["Q&A"](https://github.com/dera-multiagents/dera-core/discussions/categories/q-a)                               |
+| 🙌 **Built something cool?** | Share in ["Show and Tell"](https://github.com/dera-multiagents/dera-core/discussions/categories/show-and-tell)         |
+
+### What's in this Repository?
+
+| Component                 | Description                                                          |
+| ------------------------- | -------------------------------------------------------------------- |
+| 🐳 **Docker MCP Toolkit** | Pre-configured MCP servers running in Docker containers              |
+| ⚙️ **MCP Presets**        | Curated configurations for different workflows (dev, research, etc.) |
+| 🖥️ **IDE Configs**        | Integration configs for VS Code, Cursor, Claude Code                 |
+| 🌐 **Gateway Service**    | HTTP/SSE gateway for reliable MCP connections                        |
+
+### Quick Links
+
+- [Docker MCP Toolkit Setup](../docker-mcp-setup.md)
+- [Available Presets](../../presets/)
+- [IDE Integration Guide](../ide-integration.md)
+- [Troubleshooting Guide](../troubleshooting.md)
+
+### Proposing a New MCP Server
+
+Have an idea for a new MCP server configuration?
+
+1. Check existing [MCP proposals](https://github.com/dera-multiagents/mcp-ecosystem/labels/mcp-server)
+2. Open an issue with the `mcp-server` label
+3. Discuss in the [MCP Ecosystem category](https://github.com/dera-multiagents/dera-core/discussions/categories/mcp-ecosystem)
+
+---
+
+**License:** Apache 2.0

package/docs/community/README-community-snippet-squads.md

@@ -0,0 +1,40 @@
+# README Community Section - dera-squads
+
+> 🌐 **EN** | [PT](../pt/community/README-community-snippet-squads.md) | [ES](../es/community/README-community-snippet-squads.md)
+
+> **Purpose:** Copy this snippet into the README.md of `dera-multiagents/dera-squads` repository.
+
+---
+
+## 💬 Community & Support
+
+For discussions, questions, and community interaction, visit our central hub:
+
+👉 **[Dera Community Discussions](https://github.com/dera-multiagents/dera-core/discussions)**
+
+| Need | Where to Go |
+|------|-------------|
+| 📦 **Squad questions?** | Use the ["Squads" category](https://github.com/dera-multiagents/dera-core/discussions/categories/squads) |
+| 💡 **Feature ideas?** | Start a [Discussion in "Ideas"](https://github.com/dera-multiagents/dera-core/discussions/categories/ideas) |
+| 🐛 **Found a bug?** | [Open an issue](https://github.com/dera-multiagents/dera-squads/issues/new/choose) in **this repository** |
+| 🙏 **Need help?** | Ask in ["Q&A"](https://github.com/dera-multiagents/dera-core/discussions/categories/q-a) |
+| 🙌 **Built something cool?** | Share in ["Show and Tell"](https://github.com/dera-multiagents/dera-core/discussions/categories/show-and-tell) |
+
+### Available Squads
+
+| Squad | Description | Status |
+|-------|-------------|--------|
+| 🔄 **ETL Squad** | Data collection, transformation, and pipeline automation | Active |
+| ✍️ **Creator Squad** | Content generation, blog posts, course creation | Active |
+
+### Proposing a New Squad
+
+Have an idea for a new Dera Squad? We'd love to hear it!
+
+1. Check existing [Squad proposals](https://github.com/dera-multiagents/dera-squads/labels/new-squad)
+2. Open a [Squad Proposal issue](https://github.com/dera-multiagents/dera-squads/issues/new?template=squad-proposal.md)
+3. Discuss in the community
+
+---
+
+**Tagline:** *Dera Squads: Equipes de AI agents trabalhando com você* 🤖

package/docs/community.md

@@ -0,0 +1,227 @@
+# Dera Community
+
+> 🇧🇷 [Versão em Português](COMMUNITY-PT.md)
+
+Welcome to the Dera community!
+
+We're building the future of AI-orchestrated development together.
+
+## Our Values
+
+- **Collaboration over competition** - We grow together
+- **Inclusion** - Everyone is welcome regardless of experience level
+- **Transparency** - Open discussions, open decisions
+- **Quality** - We care about doing things right
+
+## Getting Started
+
+### First Steps
+
+1. Star the repository
+2. Read the [README](README.md)
+3. Set up your [development environment](CONTRIBUTING.md#getting-started)
+4. Introduce yourself in [Discussions](https://github.com/dera-multiagents/dera-core/discussions)
+
+### Find Your First Contribution
+
+- Look for issues labeled [`good-first-issue`](https://github.com/dera-multiagents/dera-core/labels/good-first-issue)
+- Check [`help-wanted`](https://github.com/dera-multiagents/dera-core/labels/help-wanted) for more complex tasks
+- Browse [open Discussions](https://github.com/dera-multiagents/dera-core/discussions) to help others
+
+## Communication Channels
+
+### GitHub Discussions (Primary)
+
+Our main communication hub for all Dera repositories:
+
+- **Announcements** - Project updates from maintainers
+- **General** - General discussions about Dera
+- **Ideas** - Propose new features and improvements
+- **Q&A** - Get help with technical questions
+- **Show and Tell** - Share your projects using Dera
+- **Troubleshooting** - Get help with problems
+- **Squads** - Discussions about Dera Squads (modular agent teams)
+- **MCP Ecosystem** - Discussions about MCP tools and integrations
+
+[Join the Discussion](https://github.com/dera-multiagents/dera-core/discussions)
+
+### Issue Tracker
+
+For bug reports and feature requests:
+
+- [dera-core Issues](https://github.com/dera-multiagents/dera-core/issues) - Core framework
+- [dera-squads Issues](https://github.com/dera-multiagents/dera-squads/issues) - Dera Squads
+- [mcp-ecosystem Issues](https://github.com/dera-multiagents/mcp-ecosystem/issues) - MCP tools
+
+## How to Contribute
+
+### Code Contributions
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`npm test`)
+5. Submit a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+### Non-Code Contributions
+
+We value all types of contributions:
+
+- **Documentation** - Fix typos, improve explanations
+- **Translation** - Help translate docs
+- **Bug Reports** - Report issues you find
+- **Ideas** - Share your thoughts on improvements
+- **Design** - UI/UX suggestions
+- **Advocacy** - Blog posts, talks, tutorials
+
+### Squads
+
+Create and share your own Squads (modular AI agent teams)!
+
+Squads are specialized teams of AI agents that work together on specific domains:
+- **ETL Squad** - Data collection and transformation
+- **Creator Squad** - Content generation
+
+See [docs/Squads.md](docs/Squads.md) for details on creating your own Squad.
+
+## Community Roles
+
+### Contributors
+
+Anyone who has contributed to Dera in any way.
+- Listed in our [Contributors page](https://github.com/dera-multiagents/dera-core/graphs/contributors)
+- Mentioned in release notes for significant contributions
+
+### Maintainers
+
+Core team members who review PRs and guide the project:
+
+- [@dera-multiagents](https://github.com/dera-multiagents) - Project Lead
+
+### Becoming a Maintainer
+
+Active contributors may be invited to become maintainers. We look for:
+- Consistent quality contributions
+- Helpful community interactions
+- Understanding of project goals
+
+## Recognition
+
+### Contributors Wall
+
+All contributors are recognized in our [Contributors page](https://github.com/dera-multiagents/dera-core/graphs/contributors).
+
+### Release Credits
+
+Significant contributions are credited in release notes.
+
+## Governance
+
+### Decision Making
+
+- **Minor decisions**: Maintainers can decide
+- **Major decisions**: Discussed in GitHub Discussions
+- **Breaking changes**: Require RFC process
+
+### RFC Process
+
+For significant changes:
+
+1. Open a Discussion with `[RFC]` prefix
+2. Community provides feedback
+3. Maintainers make final decision
+4. Decision is documented
+
+### Code of Conduct
+
+We follow the [Contributor Covenant](CODE_OF_CONDUCT.md). Please read and respect it.
+
+Report violations to: conduct@dera-multiagents.com
+
+## Getting Help
+
+### Stuck on something?
+
+1. Check the [Documentation](docs/)
+2. Search [existing Discussions](https://github.com/dera-multiagents/dera-core/discussions)
+3. Ask in Q&A Discussions
+4. Open a Troubleshooting discussion
+
+### Found a bug?
+
+1. Search [existing issues](https://github.com/dera-multiagents/dera-core/issues)
+2. If new, [open a bug report](https://github.com/dera-multiagents/dera-core/issues/new?template=bug_report.md)
+
+### Have an idea?
+
+1. Check if it exists in [Ideas](https://github.com/dera-multiagents/dera-core/discussions/categories/ideas)
+2. If new, [share your idea](https://github.com/dera-multiagents/dera-core/discussions/new?category=ideas)
+3. Read our [Feature Request Process](docs/FEATURE_PROCESS.md) for detailed guidelines
+
+## Project Roadmap
+
+Want to know where Dera is headed? Check out our public roadmap:
+
+- [ROADMAP.md](ROADMAP.md) - High-level vision and planned features
+- [GitHub Project](https://github.com/orgs/dera-multiagents/projects/1) - Detailed tracking board
+
+The roadmap is updated monthly and reflects community input. You can influence our direction by:
+
+1. **Voting** on ideas in [Discussions](https://github.com/dera-multiagents/dera-core/discussions/categories/ideas)
+2. **Proposing** new features via the [RFC process](/.github/RFC_TEMPLATE.md)
+3. **Contributing** directly to planned features
+
+> Roadmap items are plans, not commitments. Priorities may shift based on community needs and technical constraints.
+
+### Feature Request Process
+
+We have a structured process for proposing new features:
+
+1. **Quick Ideas** - Open a Discussion in the "Ideas" category
+2. **RFC Process** - For significant features, write an RFC using our [template](/.github/RFC_TEMPLATE.md)
+3. **Community Voting** - Use :+1: reactions to show support
+4. **Implementation** - Approved ideas move to our backlog
+
+See [Feature Request Process](docs/FEATURE_PROCESS.md) for complete details.
+
+## Resources
+
+### Learning Dera
+
+- [Getting Started Guide](docs/getting-started.md)
+- [ARCHITECTURE Overview](docs/ARCHITECTURE.md)
+- [User Guide](.dera-core/user-guide.md)
+
+### External Resources
+
+- [Dera GitHub Organization](https://github.com/dera-multiagents)
+- [Changelog](CHANGELOG.md)
+
+## Internationalization
+
+We welcome contributions in all languages!
+
+- Documentation is primarily in English
+- Community discussions can be in any language
+- Portuguese (PT-BR) translations are appreciated
+
+## Project Status
+
+- Current Version: See [releases](https://github.com/dera-multiagents/dera-core/releases)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+
+---
+
+## Questions?
+
+Can't find what you're looking for?
+Open a Discussion or reach out to the community!
+
+**Thank you for being part of the Dera community!**
+
+---
+
+*This document is maintained by the Dera community.*
+*Last updated: 2025-12-09*

package/docs/core-architecture.md

@@ -0,0 +1,223 @@
+# Dera Method: Core ARCHITECTURE
+
+> 🌐 **EN** | [PT](./pt/core-ARCHITECTURE.md) | [ES](./es/core-ARCHITECTURE.md)
+
+---
+
+## 1. Overview
+
+The Dera Method is designed to provide agentic modes, tasks and templates to allow repeatable helpful workflows be it for agile agentic development, or expansion into vastly different domains. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex tasks, guided discussions, or other meaningful domain specific flows in a predictable, high-quality manner.
+
+The systems core module facilitates a full development lifecycle tailored to the challenges of current modern AI Agentic tooling:
+
+1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
+2. **ARCHITECTURE & Design**: Defining system ARCHITECTURE and UI/UX specifications.
+3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories with extremely specific context and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
+
+## 2. System ARCHITECTURE Diagram
+
+The entire Dera-Method ecosystem is designed around the installed `dera-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
+
+```mermaid
+graph TD
+    subgraph Dera Method Project
+        subgraph Core Framework
+            A["dera-core"]
+            A --> B["agents"]
+            A --> C["agent-teams"]
+            A --> D["workflows"]
+            A --> E["templates"]
+            A --> F["tasks"]
+            A --> G["checklists"]
+            A --> H["data (KB)"]
+        end
+
+        subgraph Tooling
+            I["tools/builders/web-builder.js"]
+        end
+
+        subgraph Outputs
+            J["dist"]
+        end
+
+        B -- defines dependencies for --> E
+        B -- defines dependencies for --> F
+        B -- defines dependencies for --> G
+        B -- defines dependencies for --> H
+
+        C -- bundles --> B
+        I -- reads from --> A
+        I -- creates --> J
+    end
+
+    subgraph Target Environments
+        K["IDE (Cursor, VS Code, etc.)"]
+        L["Web UI (Gemini, ChatGPT)"]
+    end
+
+    B --> K
+    J --> L
+
+    style A fill:#1a73e8,color:#fff
+    style I fill:#f9ab00,color:#fff
+    style J fill:#34a853,color:#fff
+```
+
+## 3. Core Components
+
+The `dera-core` directory contains all the definitions and resources that give the agents their capabilities.
+
+### 3.1. Agents (`dera-core/agents/`)
+
+- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `dera.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
+- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
+- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation.
+- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
+- **Example**: The `dera` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
+
+### 3.2. Agent Teams (`dera-core/agent-teams/`)
+
+- **Purpose**: Team files (e.g., `team-all.yaml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
+- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
+
+### 3.3. Workflows (`dera-core/workflows/`)
+
+- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yaml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `dera-orchestrator` agent.
+- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
+
+### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
+
+- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies.
+  - **`templates/`**: Contains markdown templates for common documents like PRDs, ARCHITECTURE specifications, and user stories.
+  - **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story".
+  - **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or kisuke.
+  - **`data/`**: Contains the core knowledge base (`dera-kb.md`), technical preferences (`technical-preferences.md`), and other key data files.
+
+#### 3.4.1. Template Processing System
+
+A key kisukeural principle of Dera is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
+
+The Dera framework employs a sophisticated template processing system orchestrated by three key components:
+
+- **`template-format.md`** (`dera-core/utils/`): Defines the foundational markup language used throughout all Dera templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
+
+- **`create-doc.md`** (`dera-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
+
+- **`advanced-elicitation.md`** (`dera-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
+
+The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
+
+#### 3.4.2. Technical Preferences System
+
+Dera includes a personalization layer through the `technical-preferences.md` file in `dera-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
+
+**Purpose and Benefits:**
+
+- **Consistency**: Ensures all agents reference the same technical preferences
+- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
+- **Personalization**: Agents provide recommendations aligned with user preferences
+- **Learning**: Captures lessons learned and preferences that evolve over time
+
+**Content Structure:**
+The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
+
+**Integration Points:**
+
+- Templates can reference technical preferences during document generation
+- Agents suggest preferred technologies when appropriate for project requirements
+- When preferences don't fit project needs, agents explain alternatives
+- Web bundles can include preferences content for consistent behavior across platforms
+
+**Evolution Over Time:**
+Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time.
+
+## 4. The Build & Delivery Process
+
+The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter.
+
+### 4.1. Web Builder (`tools/builders/web-builder.js`)
+
+- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `dist`.
+- **Process**:
+  1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
+  2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
+  3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
+  4. **Outputs Bundle**: The final `.txt` file is saved in the `dist` directory, ready to be uploaded to a web UI.
+
+### 4.2. Environment-Specific Usage
+
+- **For IDEs**: Users interact with the agents directly via their markdown files in `dera-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
+- **For Web UIs**: Users upload a pre-built bundle from `dist`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
+
+## 5. Dera Workflows
+
+### 5.1. The Planning Workflow
+
+Before development begins, Dera follows a structured planning workflow that establishes the foundation for successful project execution:
+
+```mermaid
+graph TD
+    A["Start: Project Idea"] --> B{"Optional: senku Brainstorming"}
+    B -->|Yes| C["senku: Market Research & Analysis"]
+    B -->|No| D["Create Project Brief"]
+    C --> D["senku: Create Project Brief"]
+    D --> E["PM: Create PRD from Brief"]
+    E --> F["kisuke: Create ARCHITECTURE from PRD"]
+    F --> G["PO: Run Master Checklist"]
+    G --> H{"Documents Aligned?"}
+    H -->|Yes| I["Planning Complete"]
+    H -->|No| J["PO: Update Epics & Stories"]
+    J --> K["Update PRD/ARCHITECTURE as needed"]
+    K --> G
+    I --> L["📁 Switch to IDE"]
+    L --> M["PO: Shard Documents"]
+    M --> N["Ready for SM/Dev Cycle"]
+
+    style I fill:#34a853,color:#fff
+    style G fill:#f9ab00,color:#fff
+    style L fill:#1a73e8,color:#fff
+    style N fill:#34a853,color:#fff
+```
+
+**Key Planning Phases:**
+
+1. **Optional Analysis**: senku conducts market research and competitive analysis
+2. **Project Brief**: Foundation document created by senku or user
+3. **PRD Creation**: PM transforms brief into comprehensive product requirements
+4. **ARCHITECTURE Design**: kisuke creates technical foundation based on PRD
+5. **Validation & Alignment**: PO ensures all documents are consistent and complete
+6. **Refinement**: Updates to epics, stories, and documents as needed
+7. **Environment Transition**: Critical switch from web UI to IDE for development workflow
+8. **Document Preparation**: PO shards large documents for development consumption
+
+**Workflow Orchestration**: The `dera-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases.
+
+### 5.2. The Core Development Cycle
+
+Once the initial planning and ARCHITECTURE phases are complete, the project moves into a cyclical development workflow, as detailed in the `dera-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process.
+
+```mermaid
+graph TD
+    A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
+    B --> C["PO: Shard Arch"]
+    C --> D["Development Phase"]
+    D --> E["Scrum Master: Drafts next story from sharded epic"]
+    E --> F{"User Approval"}
+    F -->|Approved| G["Dev: Implement Story"]
+    F -->|Needs Changes| E
+    G --> H["Dev: Complete story Tasks"]
+    H --> I["Dev: Mark Ready for Review"]
+    I --> J{"User Verification"}
+    J -->|Request QA Review| K["QA: Run review-story task"]
+    J -->|Approve Without QA| M["Mark Story as Done"]
+    K --> L{"QA Review Results"}
+    L -->|Needs Work| G
+    L -->|Approved| M["Mark Story as Done"]
+    J -->|Needs Fixes| G
+    M --> E
+
+    style M fill:#34a853,color:#fff
+    style K fill:#f9ab00,color:#fff
+```
+
+This cycle continues, with the Scrum Master, Developer, and optionally QA agents working together. The QA agent provides senior developer review capabilities through the `review-story` task, offering code refactoring, quality improvements, and knowledge transfer. This ensures high code quality while maintaining development velocity.