knowzcode 0.1.0 → 0.2.1

package/knowzcode/knowzcode_loop.md

@@ -24,7 +24,7 @@
 
 ## 3. The Main Operational Loop
 
-### Phase 1A: Impact Analysis
+### 3.1 Phase 1A: Impact Analysis
 
 Receive the goal from the user. Identify the **Change Set** — all components affected by this change.
 
@@ -68,7 +68,7 @@ NodeIDs must be **domain concepts**, not tasks.
 **Historical Context:** Before proposing the Change Set, scan `knowzcode/workgroups/` for completed WorkGroups that touched similar components. Reference relevant context in your proposal.
 
 #### Quality Gate: Change Set Approval
-Present the proposed Change Set to the user. **PAUSE and await user approval.** Do NOT proceed to Phase 1B until the user explicitly approves.
+Present the proposed Change Set to the user. **PAUSE and await user approval.** Do NOT proceed to Phase 1B until the user explicitly approves. In autonomous mode, auto-approve and proceed immediately (see Section 5).
 
 Upon approval, generate a unique WorkGroupID and update `knowzcode_tracker.md` for all nodes to `[WIP]`.
 
@@ -79,7 +79,7 @@ Upon approval, generate a unique WorkGroupID and update `knowzcode_tracker.md` f
 
 ---
 
-### Phase 1B: Specification
+### 3.2 Phase 1B: Specification
 
 Draft or refine `knowzcode/specs/[NodeID].md` for all nodes in the Change Set.
 
@@ -115,13 +115,13 @@ Known limitations and future work.
 **Backward compatibility:** Old numbered-section specs remain valid until naturally touched. When finalizing, rewrite in the new format.
 
 #### Quality Gate: Spec Approval
-Present drafted specs to the user. **PAUSE and await user approval.** Log "SpecApproved" events.
+Present drafted specs to the user. **PAUSE and await user approval.** Log "SpecApproved" events. In autonomous mode, auto-approve and proceed immediately (see Section 5).
 
 **Pre-Implementation Commit:** After specs are approved, commit `knowzcode/` to create a checkpoint before implementation begins.
 
 ---
 
-### Phase 2A: Implementation (TDD MANDATORY)
+### 3.3 Phase 2A: Implementation (TDD MANDATORY)
 
 For each NodeID in the approved Change Set:
 
@@ -160,7 +160,7 @@ Report implementation results including test counts, verification iterations, an
 
 ---
 
-### Phase 2B: Completeness Audit
+### 3.4 Phase 2B: Completeness Audit
 
 An independent, READ-ONLY audit verifying what percentage of specifications were actually implemented.
 
@@ -177,11 +177,11 @@ An independent, READ-ONLY audit verifying what percentage of specifications were
 - Cancel the WorkGroup
 
 #### Quality Gate: Audit Approval
-Present audit results to the user. **PAUSE for decision.** Only proceed to Phase 3 when the user approves.
+Present audit results to the user. **PAUSE for decision.** Only proceed to Phase 3 when the user approves. In autonomous mode, auto-approve and proceed immediately unless safety exceptions apply (see Section 5).
 
 ---
 
-### Phase 3: Atomic Finalization
+### 3.5 Phase 3: Atomic Finalization
 
 Once implementation is verified and approved, execute finalization:
 
@@ -258,28 +258,66 @@ You **MUST** pause and await explicit user approval at:
 * If you encounter a critical, unresolvable issue
 * If an architecture discrepancy is too complex to fix autonomously
 
+### Autonomous Mode Override
+
+When the user conveys intent for autonomous operation — through natural language (e.g., "approve all", "preapprove", "autonomous mode", "just run through", "I trust your judgement") or the `--autonomous` flag — quality gates above are still **presented** for transparency but **auto-approved** without waiting for user input. The workflow runs from start to finalization uninterrupted.
+
+The lead should interpret the **spirit** of the user's instruction, not just exact keyword matches. If the user clearly wants the workflow to proceed without stopping, that constitutes autonomous mode activation.
+
+**Safety exceptions** — ALWAYS pause even in autonomous mode:
+* Critical, unresolvable blockers (Section 11)
+* Security vulnerabilities rated HIGH or CRITICAL
+* >3 failures on the same phase
+* Architecture discrepancies too complex to fix autonomously
+* >3 gap-fix iterations per partition without resolution
+
+Autonomous mode is per-WorkGroup and does not carry over.
+
 ---
 
 ## 6. MCP Integration (Optional but Recommended)
 
 If KnowzCode MCP server is configured (`knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`), agents can leverage vault queries to enhance every phase.
 
+**Before using MCP, read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type.** Use the vault's description to confirm the query is appropriate for that vault. If a single vault covers all types, use it for everything. Never hardcode vault names — always resolve from config.
+
+### Vault Types
+
+| Type | Purpose | Example Queries |
+|------|---------|-----------------|
+| **code** | Reference implementations, code snippets, API patterns | `"authentication middleware pattern"`, `"error handling in {framework}"` |
+| **ecosystem** | Business rules, conventions, decisions, integrations, platform knowledge | `"checkout flow rules"`, `"pricing constraints"`, `"Stripe webhook setup"` |
+| **finalizations** | WorkGroup completion summaries, outcome records | `"past decisions about {component}"`, `"similar WorkGroups"` |
+
+A project may configure one vault covering all types (common for small teams) or multiple specialized vaults. Knowz-scribe (or direct MCP calls) writes to vaults; knowz-scout has read access only. The scribe is the primary capture agent that routes writes to the correct vault based on content type.
+
 ### Phase-Specific Usage
 
 | Phase | MCP Tool | Purpose |
 |-------|----------|---------|
-| **1A (Analysis)** | `search_knowledge(research_vault, "past decisions about {domain}")` | Find prior decisions affecting components |
-| **1B (Spec)** | `ask_question(research_vault, "conventions for {component_type}?")` | Check team conventions before drafting |
-| **2A (Build)** | `search_knowledge(code_vault, "{similar_feature} implementation")` | Find reference implementations |
-| **2B (Audit)** | `ask_question(research_vault, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
-| **3 (Close)** | `create_knowledge(research_vault, ...)` | Capture patterns, decisions, workarounds |
+| **1A (Analysis)** | `search_knowledge({vault matching "ecosystem" type}, "past decisions about {domain}")` | Find prior decisions affecting components |
+| **1B (Spec)** | `ask_question({vault matching "ecosystem" type}, "conventions for {component_type}?")` | Check team conventions before drafting |
+| **2A (Build)** | `search_knowledge({vault matching "code" type}, "{similar_feature} implementation")` | Find reference implementations |
+| **2B (Audit)** | `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
+| **3 (Close)** | Delegate to knowz-scribe (or `create_knowledge` directly if no scribe) | Capture patterns, decisions, workarounds |
+
+### Knowz-Scribe (Multi-Agent Platforms)
+
+On platforms with multi-agent orchestration (e.g., Claude Code Agent Teams), **knowz-scribe** has full read/write access to MCP vaults, and **knowz-scout** has read access to MCP vaults. Both have read/write access to local knowzcode files:
+
+- Both spawned at workflow start (persistent agents, Stage 0 through Phase 3)
+- **Knowz-scribe** is the primary capture agent — receives capture messages from teammates at each quality gate (e.g., `"Capture Phase 1A: {wgid}"`), reads the WorkGroup file, extracts learnings, and writes to the appropriate vault. Handles deduplication, formatting, and routing to the correct vault by type.
+- **Knowz-scout** is the primary research agent — queries vaults for business context, conventions, and past decisions.
+- Both stay alive through the entire workflow, shut down after Phase 3 capture
+
+On platforms without multi-agent orchestration, the closer handles vault writes directly (see Section 7).
 
 ### Enterprise: Team Standards
 
-At workflow start, if enterprise vault is configured (`knowzcode/enterprise/compliance_manifest.md` has `mcp_compliance_enabled: true`):
+At workflow start, if an enterprise-type vault is configured (read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise", then check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`):
 - Pull team-wide standards and merge into quality gate criteria
-- Push audit results to enterprise vault after Phase 2B
-- Push completion records to enterprise vault after Phase 3
+- Push audit results to the resolved enterprise vault after Phase 2B
+- Push completion records to the resolved enterprise vault after Phase 3
 
 ### Graceful Degradation
 
@@ -301,45 +339,48 @@ During finalization, scan the WorkGroup for insight-worthy patterns:
 
 ### Auto-Capture Triggers
 
-Learning candidates are detected at each quality gate. If MCP is available, write concrete knowledge entries:
+Learning candidates are detected at each quality gate. Capture is delegated to the knowz-scribe agent on multi-agent platforms, or handled directly via MCP tools on single-agent platforms.
 
-**After Phase 1A approval:**
-```
-If MCP available:
-  create_knowledge(research_vault, title="Scope: {goal}",
-    content="[NodeIDs] {list}\n[Risk] {assessment}\n[Decision] {user feedback}",
-    tags=["scope", "change-set"])
-```
+**Multi-agent platforms (knowz-scribe active):**
 
-**After Phase 2A completion:**
-- Capture implementation patterns and workarounds discovered during TDD cycles
+At each quality gate, send a message to the knowz-scribe with the phase identifier:
+- After Phase 1A approval: `"Capture Phase 1A: {wgid}"`
+- After Phase 2A completion: `"Capture Phase 2A: {wgid}"`
+- After Phase 2B audit: `"Capture Phase 2B: {wgid}"`
+- After Phase 3 finalization: `"Capture Phase 3: {wgid}"`
 
-**After Phase 2B audit:**
-```
-If MCP available:
-  create_knowledge(research_vault, title="Audit: {wgid} - {score}%",
-    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
-    tags=["audit", "quality"])
-If MCP available AND enterprise vault configured:
-  create_knowledge(enterprise_vault, title="Audit: {wgid} - {score}%",
-    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
-    tags=["audit", "enterprise"])
-```
+The knowz-scribe reads the WorkGroup file, extracts relevant data, checks for duplicates, and writes to the appropriate vault. No other agent should call `create_knowledge` when the scribe is active.
 
-**After Phase 3 finalization:**
-- Capture architectural learnings and consolidation decisions (handled by closer agent)
+**Single-agent / no scribe (direct MCP writes):**
+
+If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
+
+- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {goal}", content="[NodeIDs] {list}\n[Risk] {assessment}", tags=["scope"])`
+- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles
+- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}%", content="[Findings] {gaps}\n[Security] {issues}", tags=["audit"])`
+- After Phase 2B (enterprise): If enterprise vault configured and compliance enabled, push audit results to enterprise vault
+- After Phase 3: Capture architectural learnings and consolidation decisions (handled by closer agent)
 
 ### Capture Protocol
 
-If MCP is available:
-1. Detect learning candidates from WorkGroup file content
-2. Check for duplicates via `search_knowledge` — skip if substantially similar exists
-3. Prompt user for approval before saving
-4. Create learning via `create_knowledge` with appropriate title prefix
+**When knowz-scribe is active (multi-agent platforms):**
+1. Send capture message to knowz-scribe with phase identifier and WorkGroup ID
+2. The scribe handles: vault ID resolution, duplicate checking, user approval prompting, and writing
+3. No other agent should call `create_knowledge` directly
+
+**When no knowz-scribe (single-agent / sequential):**
+1. Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
+2. Detect learning candidates from WorkGroup file content
+3. Check for duplicates via `search_knowledge` — skip if substantially similar exists
+4. Prompt user for approval before saving
+5. Only write if the targeted vault is configured — skip gracefully if not
+6. Create learning via `create_knowledge` with appropriate title prefix
 
 ### Audit Trail (Enterprise)
 
-After Phase 3, if enterprise vault is configured:
+After Phase 3:
+1. Read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise"
+2. Only push if an enterprise vault is configured
 - Push WorkGroup completion record with goal, NodeIDs, audit score, and decisions
 - Push architecture drift findings if any detected during finalization
 
@@ -378,6 +419,31 @@ When a single AI handles all phases sequentially:
 - Pause at each gate for user approval
 - All quality standards apply identically
 
+### Parallel Execution (Multi-Agent Platforms)
+
+On platforms supporting concurrent agents (Claude Code Agent Teams, future multi-agent runtimes):
+
+#### Parallelism Boundaries
+- **Between phases**: Phase 1A must produce Change Set before 1B drafts specs (scope must be approved first)
+- **Within phases**: Independent NodeIDs can be implemented/audited in parallel
+- **Across phases**: Incremental review can start on completed components while other components are still being implemented
+- **Agent persistence**: Agents can stay alive across sub-phases to avoid cold-start overhead (e.g., builder persists through audit gap loop)
+
+#### Dependency Map
+The analyst produces a dependency map alongside the Change Set, identifying:
+- Which NodeIDs share affected files (must be implemented sequentially or by same agent)
+- Which NodeIDs are independent (can be implemented in parallel)
+- Sequential dependencies (NodeID-B requires NodeID-A's output)
+
+#### Incremental Review
+The reviewer can audit completed NodeIDs before all implementation finishes. Gap findings are routed back to the implementer for targeted fixes, then re-audited. Agents persist through this gap loop — no respawning.
+
+#### Context Scouts
+Dedicated context-gathering agents can run in parallel with core analysis:
+- Local context scout: reads project history, specs, workgroups
+- Knowz scout: queries and writes to knowledge management vaults for business context (full read/write access)
+Both broadcast findings to inform analyst and architect work.
+
 ### Sequential Execution Protocol (for platforms without orchestration)
 
 For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration:

package/knowzcode/knowzcode_project.md

@@ -1,233 +1,48 @@
-# ◆ KnowzCode Project Overview: [Agent: Infer a Project Name from UserProjectIdea]
-
----
-
-**Purpose of this Document:** This `knowzcode_project.md` is a core artifact of the KnowzCode system. It provides a comprehensive high-level summary of the project, including its goals, scope, technology stack, architecture, coding standards, and quality priorities. The KnowzCode AI Agent will reference this document extensively for context and guidance throughout the development lifecycle, as detailed in `knowzcode_loop.md`.
-
----
-
-### 1. Project Goal & Core Problem
-
-*   **Goal:** [Agent: Based on `UserProjectIdea`, concisely define the main objective of this project in 1-2 sentences.]
-*   **Core Problem Solved:** [Agent: Based on `UserProjectIdea`, describe the specific user problem or need this project addresses in 1-2 sentences.]
-
----
-
-### 2. Scope & Key Features (MVP Focus)
-
-*   **Minimum Viable Product (MVP) Description:** [Agent: Briefly describe what constitutes the first usable version of the application, based on `UserProjectIdea`.]
-*   **Key Features (In Scope for MVP):**
-    *   `[Feature 1 Name]`: [Agent: Brief description of Feature 1. Infer from `UserProjectIdea`. Example: "User authentication (signup, login, logout)"]
-    *   `[Feature 2 Name]`: [Agent: Brief description of Feature 2.]
-    *   `[Feature 3 Name]`: [Agent: Brief description of Feature 3.]
-    *   *(Agent: Add more features as appropriate based on `UserProjectIdea`. Aim for 3-5 core MVP features.)*
-*   **Key Features (Explicitly OUT of Scope for MVP):**
-    *   `[Deferred Feature 1 Name]`: [Agent: Example: "Admin dashboard"]
-    *   `[Deferred Feature 2 Name]`: [Agent: Example: "Third-party API integrations beyond core needs"]
-    *   *(Agent: List 1-3 significant features that will not be part of the initial MVP to maintain focus.)*
-
----
-
-### 3. Target Audience
-
-*   **Primary User Group(s):** [Agent: Based on `UserProjectIdea`, describe the primary intended users. E.g., "Small business owners needing simple invoicing," "Students learning web development," "Gamers looking for a community platform."]
-*   **Key User Needs Addressed:** [Agent: Briefly list the key needs of the target audience that this project aims to satisfy.]
-
----
-
-### 4. Technology Stack (Specific Versions Critical for Agent)
-
-| Category             | Technology                                                                                                                                                        | Specific Version (or latest stable)      | Notes for AI Agent / Rationale                                         |
-|:---------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------|:----------------------------------------------------------------------------|
-| Language(s)          | [Agent: e.g., JavaScript (Node.js), Python. Recommend based on UserTechnicalPreferences or common platform usage. Specify version.]    | [Agent: e.g., nodejs-20, python-3.11]    | (Agent: Key for environment setup and tooling)                |
-| Backend Framework    | [Agent: e.g., Express.js, Flask, FastAPI, None. Recommend if applicable.]                                                                                        | [Agent: e.g., Express 4.18.x, Flask 2.3.x] | (Agent: Key for understanding server structure)                           |
-| Frontend Framework   | [Agent: e.g., React, Vue, Svelte, Static HTML/CSS/JS. Recommend if separate frontend envisioned.]                                                                | [Agent: e.g., React 18.2.x, Vue 3.3.x]   | (Agent: Key for UI component structure)                                    |
-| UI Library/Kit       | [Agent: e.g., Tailwind CSS, Bootstrap, Material UI, None. Recommend if applicable.]                                                                               | [Agent: e.g., Tailwind CSS 3.3.x]        |                                                                             |
-| Database             | [Agent: e.g., PostgreSQL, SQLite, MongoDB Atlas. Recommend platform-compatible options.]                                                          | [Agent: e.g., PostgreSQL 15.x]           | (Agent: Connection details via environment variables)         |
-| ORM/ODM (If any)     | [Agent: e.g., Prisma, SQLAlchemy, Drizzle ORM, Mongoose. Recommend if applicable.]                                                                               | [Agent: e.g., Prisma 5.x.x]              | (Agent: Important for DB interaction patterns and migrations)               |
-| Testing (Unit)       | [Agent: e.g., Jest, PyTest, Vitest. Recommend.]                                                                                                                  | [Agent: e.g., Jest 29.x]                 | (Agent: Use this for running unit tests)                          |
-| Testing (E2E/Integ.) | [Agent: e.g., Playwright, Cypress, Postman/Newman, None. Recommend if applicable for MVP.]                                                                       | [Agent: e.g., Playwright 1.4x.x]         | (Agent: Use this for running integration/E2E tests)               |
-| Version Control      | Git                                                                                                                                                               | N/A                                      | Repo hosted on [Agent: e.g., GitHub, GitLab, or local] |
-| Deployment Target    | [Agent: e.g., Vercel, Netlify, AWS, Local Docker]                                                                                                                                                | N/A                                      | Primary deployment target.                                              |
-| Key Libraries        | [Agent: e.g., axios for HTTP, bcryptjs for hashing. List 1-2 essential libraries and versions.]                                                                  | [Agent: Specify versions, e.g., axios@1.6.0] | (Agent: Key dependencies to install.)         |
-| Other (Specify)      |                                                                                                                                                                   |                                          |                                                                             |
-
-* **Tech Stack Rationale:** [Agent: Briefly explain why the chosen stack (especially language/framework) is suitable for this project. E.g., "Node.js with Express.js offers rapid development for web APIs and has a vast ecosystem of packages."]
-
----
-
-### 5. High-Level Architecture
-
-* **Architectural Style:** [Agent: Describe the chosen style, e.g., "Monolithic Web Application," "Serverless API with Frontend Client," "Three-Tier Architecture." Suggest a simple, robust architecture.]
-* **Key Components & Interactions (Brief Textual Description):** [Agent: Describe the main pieces and how they generally communicate. This complements `knowzcode_architecture.md`. E.g., "The React frontend client makes API calls to the Express.js backend. The backend handles business logic and interacts with the PostgreSQL database via Prisma ORM."]
-* **Diagram (Mermaid - Agent to Generate):**
-    ```mermaid
-    graph TD
-        A[User via Browser/Client] --> B(Frontend SPA - [Agent: e.g., React]);
-        B --> C{Backend API - [Agent: e.g., Express.js]};
-        C --> D[(Database - [Agent: e.g., PostgreSQL])];
-        C --> E{{External Service API (Optional - [Agent: e.g., Stripe])}};
-
-        %% Agent: Define main components and primary interaction flows based on UserProjectIdea and chosen style. Keep it simple (2-5 components).
-        %% Example Subgraph for services
-        subgraph Backend Logic
-            direction LR
-            C --- S1[Auth Service (Handles Login/Signup)];
-            C --- S2[Core Feature Service (Manages [Primary Feature])];
-        end
-    ```
-    *(Agent: Generate a SIMPLE Mermaid diagram showing 2-5 main components and their primary interactions. The main detailed flowchart is in `knowzcode_architecture.md`.)*
-
----
-
-### 6. Core Components/Modules (Logical Breakdown)
-
-* `[Component/Module 1 Name - Agent: e.g., User Authentication Module]`: [Agent: Brief responsibility. E.g., "Handles user registration, login, session management, password hashing."]
-* `[Component/Module 2 Name - Agent: e.g., Main Feature X Logic]`: [Agent: Brief responsibility. E.g., "Manages core logic for Feature X, including data processing and interactions with Y."]
-* `[Component/Module 3 Name - Agent: e.g., Primary UI View Components]`: [Agent: Brief responsibility. E.g., "Set of React components for rendering the main dashboard, forms, and user interactions."]
-* *(Agent: List 2-4 primary logical components based on the architecture and `UserProjectIdea`.)*
-
----
-
-### 7. Key UI/UX Considerations
-
-* **Overall Feel:** [Agent: Describe the desired user experience. E.g., "Simple and intuitive," "Modern and professional," "Fast and responsive." Infer from `UserProjectIdea` or suggest a sensible default.]
-* **Key Principles:**
-    * `[Principle 1]`: [Agent: e.g., "Clarity: Ensure clear navigation and unambiguous calls to action."]
-    * `[Principle 2]`: [Agent: e.g., "Efficiency: Minimize clicks and streamline common workflows."]
-    * `[Principle 3]`: [Agent: e.g., "Responsiveness: Basic usability on common screen sizes (desktop primary, mobile secondary consideration for MVP)."]
-
----
-
-### 8. Coding Standards & Conventions
-
-* **Primary Style Guide:** [Agent: e.g., "Airbnb JavaScript Style Guide (with Prettier for formatting)," "PEP 8 for Python (with Black for formatting)"]
-* **Formatter:** [Agent: e.g., "Prettier (config in `.prettierrc` - use default if not specified)," "Black (Python)"] (Agent: You will apply this during ARC-Based Verification)
-* **Linter:** [Agent: e.g., "ESLint (config in `.eslintrc.js` - use default if not specified)," "Flake8 (Python)"] (Agent: You will apply this during ARC-Based Verification)
-* **File Naming Conventions:** [Agent: e.g., `kebab-case.js` for files, `PascalCase.jsx` for React components, `snake_case.py` for Python files]
-* **Commit Message Convention:** [Agent: e.g., "Conventional Commits (e.g., `feat: add login button`, `fix: correct validation logic`)"]
-* **Code Commenting Style:** [Agent: e.g., "JSDoc for public functions/methods," "Python docstrings (Google style)," "Use comments sparingly only for complex, non-obvious logic."]
-* **Other Key Standards:**
-    * [Agent: e.g., "Avoid magic numbers/strings; use named constants."]
-    * [Agent: e.g., "All API endpoints must have basic input validation on the server-side."]
-    * [Agent: e.g., "Relative imports for intra-project modules."]
-
-### 8.1 Component Classification Criteria
-
-* **Standard**: Simple components with clear inputs/outputs, minimal business logic
-* **Complex**: Components with significant business logic, multiple dependencies, or state management
-* **Critical**: Components handling security, payments, user data, or system stability
-
----
-
-### 9. Key Quality Criteria Focus (Priorities from `knowzcode/knowzcode_log.md`)
-* This project will prioritize the following **Top 3-5 quality criteria** from the "Reference Quality Criteria" section of `knowzcode/knowzcode_log.md`. Agent, you should pay special attention to these during ARC-Based Verification.
-    1.  [Agent: Suggest Priority 1 Quality Criterion - e.g., Reliability (Robust error handling)]
-    2.  [Agent: Suggest Priority 2 Quality Criterion - e.g., Maintainability (Clear, modular code)]
-    3.  [Agent: Suggest Priority 3 Quality Criterion - e.g., Security (Secure auth practices, input validation)]
-    4.  [Agent: Suggest Optional Priority 4, if applicable]
-    5.  [Agent: Suggest Optional Priority 5, if applicable]
-* **Rationale for Priorities:** [Agent: Briefly explain why these priorities are important for this specific project based on `UserProjectIdea`.]
-
----
-
-### 10. Testing Strategy
-
-* **Required Test Types for MVP:**
-    * `Unit Tests`: [Agent: e.g., "Required for all core business logic functions/modules and critical utility functions."]
-    * `Integration Tests`: [Agent: e.g., "Required for API endpoint interactions and key service-to-service integrations."]
-    * `E2E Tests (Optional for MVP)`: [Agent: e.g., "Minimal set for 1-2 primary user flows (e.g., signup-login-perform core action)."]
-* **Testing Framework(s) & Version(s):** [Agent: Refer to Technology Stack, e.g., "Jest 29.x for unit/integration (JavaScript)", "PyTest 7.x for Python".]
-* **Test File Location & Naming:** [Agent: e.g., "Test files located adjacent to source files (`module.test.js`) or in a dedicated `__tests__`/`tests/` directory. Test names should be descriptive: `it('should return sum of two numbers')`."]
-* **Minimum Code Coverage Target (Conceptual Goal):** [Agent: e.g., "Aim for >70% for unit-tested core logic." State as an aim, not a strict CI blocker for MVP unless specified by user.]
-
----
-
-### 11. Initial Setup Steps (Conceptual for a new developer/environment)
-
-1.  **Clone Repository:** `git clone [repository_url]`
-2.  **Install Language/Tools:** (Agent: Check versions against Tech Stack; use `knowzcode/EnvironmentContext.md` for specific commands).
-3.  **Install Dependencies:** (Agent: Use the dependency manager defined in `knowzcode/EnvironmentContext.md`, e.g., `npm install`).
-4.  **Environment Variables & Secrets:**
-    * [Agent: List any anticipated required environment variables based on common app needs or `UserProjectIdea`, e.g., `DATABASE_URL`, `SESSION_SECRET`, `ANY_EXTERNAL_API_KEY`].
-    * (Agent: Secrets must be stored securely, e.g., in a `.env` file loaded at runtime, and never committed to version control).
-5.  **Database Setup (If applicable):**
-    * [Agent: e.g., "Run database migrations using the command specified in `knowzcode/EnvironmentContext.md`, such as `npx prisma migrate dev`."]
-6.  **Run Development Server:**
-    * [Agent: Specify the typical run command for the chosen stack, e.g., `npm run dev`, `python main.py`.]
-    * (Agent: The server must bind to the host and port specified in `knowzcode/EnvironmentContext.md`).
-
----
-
-### 12. Key Architectural Decisions & Rationale
-
-* **Decision 1: [Agent: e.g., Choice of Primary Language/Framework - e.g., Node.js with Express.js]**
-    * **Rationale:** [Agent: e.g., "Chosen for its non-blocking I/O suitable for web applications and its large ecosystem of packages." If user specified, use their rationale or infer and confirm.]
-* **Decision 2: [Agent: e.g., Database Choice - e.g., PostgreSQL]**
-    * **Rationale:** [Agent: e.g., "Selected for its robustness, SQL capabilities, and wide support from ORMs and cloud providers."]
-* **(Optional) Decision 3: [Agent: e.g., Architectural Style - e.g., Monolithic App for MVP]**
-    * **Rationale:** [Agent: e.g., "A monolithic approach was chosen for the MVP to simplify initial development and deployment, reducing complexity. Microservices can be considered for future scaling if needed."]
-
----
-
-### 13. Repository Link
-
-* `[Agent: Link to Git Repository. User/Orchestrator will confirm/update.]` (Can be placeholder initially: "[To be confirmed/updated]")
-
----
-
-### 14. Dependencies & Third-Party Services (Key Ones for MVP)
-
-* **[Service 1 Name - Agent: e.g., PostgreSQL Database]:**
-    * Purpose: Primary data storage.
-    * Integration: Via `DATABASE_URL` environment variable.
-* **(Optional) [External API Name - Agent: e.g., Stripe API]:**
-    * Purpose: [Agent: e.g., "To handle payments."]
-    * Integration: [Agent: e.g., "Via HTTP POST requests to their API endpoint. Requires API key."]
-    * Required Credentials: `[Agent: e.g., STRIPE_API_KEY]` (To be stored as an environment variable).
-* *(Agent: List only essential external services for the MVP based on `UserProjectIdea`.)*
-
----
-
-### 15. Security Considerations (Initial High-Level)
-
-* **Authentication:** [Agent: e.g., "Session-based authentication using secure, HTTP-only cookies and a `SESSION_SECRET` stored as an environment variable / JWT-based authentication for APIs." Passwords **MUST** be hashed (e.g., using bcrypt or argon2).]
-* **Authorization:** [Agent: e.g., "Basic role-based access control if multiple user types exist. Check authorization on the server-side for all sensitive operations."]
-* **Input Validation:** [Agent: e.g., "All user inputs (forms, API request bodies/params) MUST be validated on the server-side to prevent common injection attacks (XSS, SQLi - though ORM mitigates SQLi largely)."]
-* **Data Protection:**
-    * "Sensitive data (e.g., PII, passwords) handled with care. Avoid logging sensitive data."
-    * "Use HTTPS in production environments."
-* **Dependency Management:** [Agent: e.g., "Dependencies will be kept updated. Use `npm audit` / `pip-audit` or similar tools periodically."]
-* **Secrets Management:** "All API keys, database credentials, and other secrets **MUST** be stored as environment variables and not hardcoded."
-
----
-
-### 16. Performance Requirements (Initial Qualitative Goals)
-
-* **Response Time:** [Agent: e.g., "Web pages and API responses should generally feel responsive, aiming for <500ms for common operations under typical load." Suggest sensible defaults.]
-* **Load Capacity (Conceptual for MVP):** [Agent: e.g., "Application should handle a small number of concurrent users smoothly (e.g., 10-50)."]
-* **Scalability Approach (Future Consideration):** [Agent: e.g., "For MVP, vertical scaling is the primary approach. Horizontal scaling or more complex strategies are future considerations."]
-
----
-
-### 17. Monitoring & Observability (Basic for MVP)
-
-* **Logging Strategy (Application-level):**
-    * [Agent: e.g., "Structured JSON logging to console for key application events, errors, and requests (e.g., using a library like Pino for Node.js or standard Python logging module)."]
-    * "Include timestamps, log levels (INFO, WARN, ERROR), and relevant context (e.g., request ID)."
-* **Monitoring Tools:** [Agent: e.g., "For MVP, rely on standard console/file logs. No complex external tools unless user specifies."]
-* **Key Metrics to Observe (Qualitative):** Error rates in logs, general application responsiveness.
-* **Alerting Criteria (Manual for MVP):** [Agent: e.g., "Monitor logs for frequent errors or performance degradation manually."]
-
----
-
-### 18. Links to Other KnowzCode Artifacts
-* **Agent Main Loop & Protocol:** `knowzcode/knowzcode_loop.md`
-* **Operational Record & Quality Criteria:** `knowzcode/knowzcode_log.md`
-* **Architectural Flowchart (This Project):** `knowzcode/knowzcode_architecture.md`
-* **Status Map (This Project):** `knowzcode/knowzcode_tracker.md`
-* **Component Specifications Directory:** `knowzcode/specs/`
-* **Environment Protocol:** `knowzcode/environment_context.md` (or equivalent)
-
----
-*(Agent: This document, once populated by you based on user input and sensible defaults, will become the single source of truth for high-level project information and guidelines. It will be kept up-to-date if major project parameters change.)*
+# Project Overview
+
+## Goal
+*   **Goal:** [concise project objective — 1-2 sentences]
+*   **Core Problem:** [specific user problem this solves — 1-2 sentences]
+
+## Stack
+
+| Category | Technology | Version |
+|:---------|:-----------|:--------|
+| Language | | |
+| Backend Framework | | |
+| Frontend Framework | | |
+| Database | | |
+| ORM/ODM | | |
+| Testing (Unit) | | |
+| Testing (E2E) | | |
+| Key Libraries | | |
+
+## Architecture
+*   **Style:** [e.g., Monolithic, Microservices, Serverless]
+*   **Key Components:** [2-3 sentence description of main components and interactions]
+
+## Standards
+*   **Formatter:** [e.g., Prettier, Black]
+*   **Linter:** [e.g., ESLint, Flake8]
+*   **Test Framework:** [e.g., Jest, PyTest]
+*   **Commit Convention:** [e.g., Conventional Commits]
+*   **File Naming:** [e.g., kebab-case.js, PascalCase.tsx]
+
+### Component Classification
+* **Standard**: Simple components, clear inputs/outputs, minimal business logic
+* **Complex**: Significant business logic, multiple dependencies, state management
+* **Critical**: Security, payments, user data, system stability
+
+## Testing
+*   **Unit Tests:** Required for core business logic and utilities
+*   **Integration Tests:** Required for API endpoints and service interactions
+*   **E2E Tests:** [Optional for MVP — describe scope if applicable]
+*   **Coverage Target:** [e.g., >70% for core logic]
+*   **Test Location:** [e.g., adjacent `*.test.js` or `tests/` directory]
+
+## Security Priorities
+*   **Authentication:** [method — session-based, JWT, etc. Passwords MUST be hashed]
+*   **Authorization:** [approach — RBAC, ownership checks, etc.]
+*   **Input Validation:** All user inputs validated server-side
+*   **Secrets:** Environment variables only, never hardcoded
+*   **Dependencies:** Regular `npm audit` / `pip-audit` checks