monoco-toolkit 0.2.5__py3-none-any.whl → 0.2.8__py3-none-any.whl

monoco/features/issue/validator.py

@@ -6,7 +6,9 @@ from pathlib import Path
 from monoco.core.lsp import Diagnostic, DiagnosticSeverity, Range, Position
 from monoco.core.config import get_config
 from monoco.features.i18n.core import detect_language
-from .models import IssueMetadata, IssueStatus, IssueStage, IssueType
+from .models import IssueMetadata, IssueType
+from .domain.parser import MarkdownParser
+from .domain.models import ContentBlock
 
 class IssueValidator:
     """
@@ -20,14 +22,41 @@ class IssueValidator:
     def validate(self, meta: IssueMetadata, content: str, all_issue_ids: Set[str] = set()) -> List[Diagnostic]:
         diagnostics = []
         
+        # Parse Content into Blocks (Domain Layer)
+        # Handle case where content might be just body (from update_issue) or full file
+        if content.startswith("---"):
+            try:
+                issue_domain = MarkdownParser.parse(content)
+                blocks = issue_domain.body.blocks
+                has_frontmatter = True
+            except Exception:
+                # Fallback if parser fails (e.g. invalid YAML)
+                # We continue with empty blocks or try partial parsing?
+                # For now, let's try to parse blocks ignoring FM
+                lines = content.splitlines()
+                # Find end of FM
+                start_line = 0
+                if lines[0].strip() == "---":
+                    for i in range(1, len(lines)):
+                        if lines[i].strip() == "---":
+                            start_line = i + 1
+                            break
+                blocks = MarkdownParser._parse_blocks(lines[start_line:], start_line_offset=start_line)
+                has_frontmatter = True
+        else:
+            # Assume content is just body
+            lines = content.splitlines()
+            blocks = MarkdownParser._parse_blocks(lines, start_line_offset=0)
+            has_frontmatter = False
+
         # 1. State Matrix Validation
         diagnostics.extend(self._validate_state_matrix(meta, content))
         
-        # 2. Content Completeness (Checkbox check)
-        diagnostics.extend(self._validate_content_completeness(meta, content))
+        # 2. State Requirements (Strict Verification)
+        diagnostics.extend(self._validate_state_requirements(meta, blocks))
         
-        # 3. Structure Consistency (Headings)
-        diagnostics.extend(self._validate_structure(meta, content))
+        # 3. Structure Consistency (Headings) - Using Blocks
+        diagnostics.extend(self._validate_structure_blocks(meta, blocks))
         
         # 4. Lifecycle/Integrity (Solution, etc.)
         diagnostics.extend(self._validate_integrity(meta, content))
@@ -38,8 +67,8 @@ class IssueValidator:
         # 6. Time Consistency
         diagnostics.extend(self._validate_time_consistency(meta, content))
 
-        # 7. Checkbox Syntax
-        diagnostics.extend(self._validate_checkbox_logic(content))
+        # 7. Checkbox Syntax - Using Blocks
+        diagnostics.extend(self._validate_checkbox_logic_blocks(blocks))
         
         # 8. Language Consistency
         diagnostics.extend(self._validate_language_consistency(meta, content))
@@ -97,56 +126,106 @@ class IssueValidator:
         diagnostics = []
         
         # Check based on parsed metadata (now that auto-correction is disabled)
-        if meta.status == IssueStatus.CLOSED and meta.stage != IssueStage.DONE:
+        if meta.status == "closed" and meta.stage != "done":
             line = self._get_field_line(content, "status")
             diagnostics.append(self._create_diagnostic(
-                f"State Mismatch: Closed issues must be in 'Done' stage (found: {meta.stage.value if meta.stage else 'None'})", 
+                f"State Mismatch: Closed issues must be in 'Done' stage (found: {meta.stage if meta.stage else 'None'})", 
                 DiagnosticSeverity.Error,
                 line=line
             ))
         
-        if meta.status == IssueStatus.BACKLOG and meta.stage != IssueStage.FREEZED:
+        if meta.status == "backlog" and meta.stage != "freezed":
             line = self._get_field_line(content, "status")
             diagnostics.append(self._create_diagnostic(
-                f"State Mismatch: Backlog issues must be in 'Freezed' stage (found: {meta.stage.value if meta.stage else 'None'})", 
+                f"State Mismatch: Backlog issues must be in 'Freezed' stage (found: {meta.stage if meta.stage else 'None'})", 
                 DiagnosticSeverity.Error,
                 line=line
             ))
 
         return diagnostics
 
-    def _validate_content_completeness(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
+    def _validate_state_requirements(self, meta: IssueMetadata, blocks: List[ContentBlock]) -> List[Diagnostic]:
         diagnostics = []
-        # Checkbox regex: - [ ] or - [x] or - [-] or - [/]
-        checkboxes = re.findall(r"-\s*\[([ x\-/])\]", content)
         
-        if len(checkboxes) < 2:
-            diagnostics.append(self._create_diagnostic(
-                "Content Incomplete: Ticket must contain at least 2 checkboxes (AC & Tasks).",
-                DiagnosticSeverity.Warning
-            ))
-            
-        if meta.stage in [IssueStage.REVIEW, IssueStage.DONE]:
-            # No empty checkboxes allowed
-            if ' ' in checkboxes:
-                # Find the first occurrence line
-                lines = content.split('\n')
-                first_line = 0
-                for i, line in enumerate(lines):
-                    if re.search(r"-\s*\[ \]", line):
-                        first_line = i
-                        break
-                        
-                diagnostics.append(self._create_diagnostic(
-                    f"Incomplete Tasks: Issue in {meta.stage} cannot have unchecked boxes.",
-                    DiagnosticSeverity.Error,
-                    line=first_line
-                ))
+        # 1. Map Blocks to Sections
+        sections = {"tasks": [], "ac": [], "review": []}
+        current_section = None
+        
+        for block in blocks:
+            if block.type == "heading":
+                title = block.content.strip().lower()
+                # Parse title to identify sections (supporting Chinese and English synonyms)
+                if any(kw in title for kw in ["technical tasks", "工作包", "技术任务", "key deliverables", "关键交付", "重点工作", "子功能", "子故事", "child features", "stories", "需求", "requirements", "implementation", "实现", "交付", "delivery", "规划", "plan", "tasks", "任务"]):
+                    current_section = "tasks"
+                elif any(kw in title for kw in ["acceptance criteria", "验收标准", "交付目标", "验收"]):
+                    current_section = "ac"
+                elif any(kw in title for kw in ["review comments", "确认事项", "评审记录", "复盘记录", "review", "评审", "确认"]):
+                    current_section = "review"
+                elif title.startswith("###"):
+                    # Subheading: allow continued collection for the current section
+                    pass
+                else:
+                    current_section = None
+            elif block.type == "task_item":
+                if current_section and current_section in sections:
+                    sections[current_section].append(block)
+
+        # 2. Logic: DOING -> Must have defined tasks
+        if meta.stage in ["doing", "review", "done"]:
+             if not sections["tasks"]:
+                 # We can't strictly point to a line if section missing, but we can point to top/bottom
+                 # Or just a general error.
+                 diagnostics.append(self._create_diagnostic(
+                     "State Requirement (DOING+): Must define 'Technical Tasks' (at least 1 checkbox).",
+                     DiagnosticSeverity.Warning
+                 ))
+
+        # 3. Logic: REVIEW -> Tasks must be Completed ([x]) or Cancelled ([~], [+])
+        # No [ ] (ToDo) or [-]/[/] (Doing) allowed.
+        if meta.stage in ["review", "done"]:
+            for block in sections["tasks"]:
+                 content = block.content.strip()
+                 # Check for explicit illegal states
+                 if re.search(r"-\s*\[\s+\]", content):
+                      diagnostics.append(self._create_diagnostic(
+                          f"State Requirement ({meta.stage.upper()}): Technical Tasks must be resolved. Found Todo [ ]: '{content}'",
+                          DiagnosticSeverity.Error,
+                          line=block.line_start
+                      ))
+                 elif re.search(r"-\s*\[[-\/]]", content):
+                      diagnostics.append(self._create_diagnostic(
+                          f"State Requirement ({meta.stage.upper()}): Technical Tasks must be finished (not Doing). Found Doing [-]: '{content}'",
+                          DiagnosticSeverity.Error,
+                          line=block.line_start
+                      ))
+
+        # 4. Logic: DONE -> AC must be Verified ([x])
+        if meta.stage == "done":
+             for block in sections["ac"]:
+                 content = block.content.strip()
+                 if not re.search(r"-\s*\[[xX]\]", content):
+                      diagnostics.append(self._create_diagnostic(
+                          f"State Requirement (DONE): Acceptance Criteria must be passed ([x]). Found: '{content}'",
+                          DiagnosticSeverity.Error,
+                          line=block.line_start
+                      ))
+             
+             # 5. Logic: DONE -> Review Checkboxes (if any) must be Resolved ([x] or [~])
+             for block in sections["review"]:
+                 content = block.content.strip()
+                 # Must be [x], [X], [~], [+]
+                 # Therefore [ ], [-], [/] are invalid blocking states
+                 if re.search(r"-\s*\[[\s\-\/]\]", content):
+                      diagnostics.append(self._create_diagnostic(
+                          f"State Requirement (DONE): Actionable Review Comments must be resolved ([x] or [~]). Found: '{content}'",
+                          DiagnosticSeverity.Error,
+                          line=block.line_start
+                      ))
+                      
         return diagnostics
 
-    def _validate_structure(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
+    def _validate_structure_blocks(self, meta: IssueMetadata, blocks: List[ContentBlock]) -> List[Diagnostic]:
         diagnostics = []
-        lines = content.split('\n')
         
         # 1. Heading check: ## {issue-id}: {issue-title}
         expected_header = f"## {meta.id}: {meta.title}"
@@ -156,19 +235,25 @@ class IssueValidator:
         review_header_found = False
         review_content_found = False
         
-        for i, line in enumerate(lines):
-            line_stripped = line.strip()
-            if line_stripped == expected_header:
-                header_found = True
-            
-            if line_stripped == "## Review Comments":
-                review_header_found = True
-                # Check near lines for content
-                # This is a naive check (next line is not empty)
-                if i + 1 < len(lines) and lines[i+1].strip():
-                     review_content_found = True
-                elif i + 2 < len(lines) and lines[i+2].strip():
-                     review_content_found = True
+        review_header_index = -1
+        
+        for i, block in enumerate(blocks):
+            if block.type == 'heading':
+                stripped = block.content.strip()
+                if stripped == expected_header:
+                    header_found = True
+                
+                if stripped == "## Review Comments":
+                    review_header_found = True
+                    review_header_index = i
+        
+        # Check content after review header
+        if review_header_found:
+            # Check if there are blocks after review_header_index that are NOT empty
+            for j in range(review_header_index + 1, len(blocks)):
+                if blocks[j].type != 'empty':
+                    review_content_found = True
+                    break
 
         if not header_found:
              diagnostics.append(self._create_diagnostic(
@@ -176,7 +261,7 @@ class IssueValidator:
                  DiagnosticSeverity.Warning
              ))
              
-        if meta.stage in [IssueStage.REVIEW, IssueStage.DONE]:
+        if meta.stage in ["review", "done"]:
             if not review_header_found:
                 diagnostics.append(self._create_diagnostic(
                     "Review Requirement: Missing '## Review Comments' section.",
@@ -191,21 +276,87 @@ class IssueValidator:
 
     def _validate_integrity(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
         diagnostics = []
-        if meta.status == IssueStatus.CLOSED and not meta.solution:
+        if meta.status == "closed" and not meta.solution:
             line = self._get_field_line(content, "status")
             diagnostics.append(self._create_diagnostic(
                 f"Data Integrity: Closed issue {meta.id} missing 'solution' field.",
                 DiagnosticSeverity.Error,
                 line=line
             ))
+            
+        # Tags Integrity Check
+        # Requirement: tags field must carry parent dependencies and related issue id
+        required_tags = set()
+        
+        # Self ID
+        required_tags.add(f"#{meta.id}")
+        
+        if meta.parent:
+            # Strip potential user # if accidentally added in models, though core stripped it
+            # But here we want the tag TO HAVE #
+             p = meta.parent if not meta.parent.startswith("#") else meta.parent[1:]
+             required_tags.add(f"#{p}")
+             
+        for d in meta.dependencies:
+             _d = d if not d.startswith("#") else d[1:]
+             required_tags.add(f"#{_d}")
+             
+        for r in meta.related:
+             _r = r if not r.startswith("#") else r[1:]
+             required_tags.add(f"#{_r}")
+             
+        current_tags = set(meta.tags) if meta.tags else set()
+        missing_tags = required_tags - current_tags
+        
+        if missing_tags:
+            line = self._get_field_line(content, "tags")
+            # If tags field doesn't exist, line is 0, which is fine
+            # We join them for display
+            missing_str = ", ".join(sorted(missing_tags))
+            diagnostics.append(self._create_diagnostic(
+                f"Tag Check: Missing required context tags: {missing_str}",
+                DiagnosticSeverity.Warning,
+                line=line
+            ))
+            
         return diagnostics
         
     def _validate_references(self, meta: IssueMetadata, content: str, all_ids: Set[str]) -> List[Diagnostic]:
         diagnostics = []
+        
+        # Malformed ID Check
+        if meta.parent and meta.parent.startswith("#"):
+             line = self._get_field_line(content, "parent")
+             diagnostics.append(self._create_diagnostic(
+                f"Malformed ID: Parent '{meta.parent}' should not start with '#'.",
+                DiagnosticSeverity.Warning,
+                line=line
+             ))
+
+        if meta.dependencies:
+            for dep in meta.dependencies:
+                if dep.startswith("#"):
+                    line = self._get_field_line(content, "dependencies")
+                    diagnostics.append(self._create_diagnostic(
+                        f"Malformed ID: Dependency '{dep}' should not start with '#'.",
+                        DiagnosticSeverity.Warning,
+                        line=line
+                    ))
+
+        if meta.related:
+            for rel in meta.related:
+                if rel.startswith("#"):
+                    line = self._get_field_line(content, "related")
+                    diagnostics.append(self._create_diagnostic(
+                        f"Malformed ID: Related '{rel}' should not start with '#'.",
+                        DiagnosticSeverity.Warning,
+                        line=line
+                    ))
+
         if not all_ids:
             return diagnostics
             
-        if meta.parent and meta.parent not in all_ids:
+        if meta.parent and meta.parent not in all_ids and not meta.parent.startswith("#"):
              line = self._get_field_line(content, "parent")
              diagnostics.append(self._create_diagnostic(
                 f"Broken Reference: Parent '{meta.parent}' not found.",
@@ -221,6 +372,42 @@ class IssueValidator:
                     DiagnosticSeverity.Error,
                     line=line
                  ))
+                 
+        # Body Reference Check
+        # Regex for generic issue ID: (EPIC|FEAT|CHORE|FIX)-\d{4}
+        # We scan line by line to get line numbers
+        lines = content.split('\n')
+        # Skip frontmatter for body check to avoid double counting (handled above)
+        in_fm = False
+        fm_end = 0
+        for i, line in enumerate(lines):
+            if line.strip() == '---':
+                if not in_fm: in_fm = True
+                else: 
+                    fm_end = i
+                    break
+        
+        for i, line in enumerate(lines):
+            if i <= fm_end: continue # Skip frontmatter
+            
+            # Find all matches
+            matches = re.finditer(r"\b((?:EPIC|FEAT|CHORE|FIX)-\d{4})\b", line)
+            for match in matches:
+                ref_id = match.group(1)
+                if ref_id != meta.id and ref_id not in all_ids:
+                     # Check if it's a namespaced ID? The regex only catches local IDs.
+                     # If users use MON::FEAT-0001, the regex might catch FEAT-0001.
+                     # But all_ids contains full IDs (potentially namespaced).
+                     # Simple logic: if ref_id isn't in all_ids, check if any id ENDS with ref_id
+                     
+                     found_namespaced = any(known.endswith(f"::{ref_id}") for known in all_ids)
+                     
+                     if not found_namespaced:
+                        diagnostics.append(self._create_diagnostic(
+                            f"Broken Reference: Issue '{ref_id}' not found.",
+                            DiagnosticSeverity.Warning,
+                            line=i
+                        ))
         return diagnostics
 
     def _validate_time_consistency(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
@@ -249,21 +436,20 @@ class IssueValidator:
 
         return diagnostics
 
-    def _validate_checkbox_logic(self, content: str) -> List[Diagnostic]:
+    def _validate_checkbox_logic_blocks(self, blocks: List[ContentBlock]) -> List[Diagnostic]:
         diagnostics = []
-        lines = content.split('\n')
         
-        for i, line in enumerate(lines):
-            stripped = line.lstrip()
-            
-            # Syntax Check: - [?]
-            if stripped.startswith("- ["):
-                match = re.match(r"- \[([ x\-/])\]", stripped)
+        for block in blocks:
+            if block.type == 'task_item':
+                content = block.content.strip()
+                # Syntax Check: - [?]
+                # Added supported chars: /, ~, +
+                match = re.match(r"- \[([ x\-/~+])\]", content)
                 if not match:
                     # Check for Common errors
-                    if re.match(r"- \[.{2,}\]", stripped): # [xx] or [  ]
-                         diagnostics.append(self._create_diagnostic("Invalid Checkbox: Use single character [ ], [x], [-], [/]", DiagnosticSeverity.Error, i))
-                    elif re.match(r"- \[([^ x\-/])\]", stripped): # [v], [o]
-                         diagnostics.append(self._create_diagnostic("Invalid Checkbox Status: Use [ ], [x], [-], [/]", DiagnosticSeverity.Error, i))
+                    if re.match(r"- \[.{2,}\]", content): # [xx] or [  ]
+                         diagnostics.append(self._create_diagnostic("Invalid Checkbox: Use single character [ ], [x], [-], [/]", DiagnosticSeverity.Error, block.line_start))
+                    elif re.match(r"- \[([^ x\-/~+])\]", content): # [v], [o]
+                         diagnostics.append(self._create_diagnostic("Invalid Checkbox Status: Use [ ], [x], [/], [~]", DiagnosticSeverity.Error, block.line_start))
         
         return diagnostics

monoco/features/spike/core.py

@@ -1,12 +1,12 @@
 import os
 import shutil
 import subprocess
-import yaml
+
 from pathlib import Path
 from typing import Dict, Optional, List, Any
 from rich.console import Console
 
-from monoco.core.config import get_config
+from monoco.core.config import get_config, load_raw_config, save_raw_config, ConfigScope
 
 console = Console()
 
@@ -29,26 +29,10 @@ def run_git_command(cmd: List[str], cwd: Path) -> bool:
         console.print("[red]Error:[/red] git command not found.")
         return False
 
-def get_config_file_path(root: Path) -> Path:
-    """Determine the config file to update."""
-    # Standard: .monoco/project.yaml
-    hidden = root / ".monoco" / "project.yaml"
-    
-    # Ensure parent exists
-    hidden.parent.mkdir(exist_ok=True)
-    return hidden
-
 def update_config_repos(root: Path, repo_name: str, repo_url: str, remove: bool = False):
     """Update the repos list in the config file."""
-    config_path = get_config_file_path(root)
-    
-    data = {}
-    if config_path.exists():
-        try:
-            with open(config_path, "r") as f:
-                data = yaml.safe_load(f) or {}
-        except Exception:
-            data = {}
+    # Use core config utils
+    data = load_raw_config(ConfigScope.PROJECT, project_root=str(root))
             
     # Ensure structure exists
     if "project" not in data:
@@ -62,8 +46,7 @@ def update_config_repos(root: Path, repo_name: str, repo_url: str, remove: bool
     else:
         data["project"]["spike_repos"][repo_name] = repo_url
         
-    with open(config_path, "w") as f:
-        yaml.dump(data, f, sort_keys=False, default_flow_style=False)
+    save_raw_config(ConfigScope.PROJECT, data, project_root=str(root))
 
 def ensure_gitignore(root: Path, target_dir_name: str):
     """Ensure the target directory is in .gitignore."""

monoco/features/spike/resources/zh/SKILL.md

@@ -9,7 +9,7 @@ description: 管理用于研究和学习的外部参考仓库。提供对精选
 
 ## 概述
 
-Spike 功能允许你：
+Spike 功能允许你:
 
 - **添加外部仓库**作为只读参考
 - **同步仓库内容**到本地 `.references/` 目录
@@ -50,7 +50,7 @@ monoco spike list
 
 ## 配置
 
-Spike 仓库在 `.monoco/config.yaml` 中配置：
+Spike 仓库在 `.monoco/config.yaml` 中配置:
 
 ```yaml
 project:

monoco/main.py

@@ -99,15 +99,7 @@ from monoco.core.sync import sync_command, uninstall_command
 app.command(name="sync")(sync_command)
 app.command(name="uninstall")(uninstall_command)
 
-@app.command(name="doctor")
-def doctor_cmd(
-    force: bool = typer.Option(False, "--force", "-f", help="Force refresh of agent state")
-):
-    """
-    Diagnose Agent Environment.
-    """
-    from monoco.features.agent.doctor import doctor
-    doctor(force)
+
 
 @app.command()
 def info():
@@ -161,26 +153,10 @@ app.add_typer(config_cmd.app, name="config", help="Manage configuration")
 app.add_typer(project_cmd.app, name="project", help="Manage projects")
 app.add_typer(workspace_cmd.app, name="workspace", help="Manage workspace")
 
-from monoco.features.agent import commands as agent_cmd
-app.add_typer(agent_cmd.app, name="agent", help="Delegate tasks to Agent CLIs")
+
 
 from monoco.daemon.commands import serve
 app.command(name="serve")(serve)
 
-@app.command()
-def pty(
-    host: str = "127.0.0.1",
-    port: int = 3124,
-    cwd: Optional[str] = None
-):
-    """
-    Start the Monoco PTY Daemon (WebSocket).
-    """
-    from monoco.features.pty.server import run_pty_server
-    from pathlib import Path
-    
-    path = Path(cwd) if cwd else None
-    run_pty_server(host, port, path)
-
 if __name__ == "__main__":
     app()

monoco_toolkit-0.2.8.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: monoco-toolkit
+Version: 0.2.8
+Summary: Agent Native Toolkit for Monoco - Task Management & Kanban for AI Agents
+Project-URL: Homepage, https://monoco.io
+Project-URL: Repository, https://github.com/IndenScale/Monoco
+Project-URL: Documentation, https://monoco.io/docs
+Project-URL: Issues, https://github.com/IndenScale/Monoco/issues
+Author-email: Monoco Team <dev@monoco.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-native,ai-agents,cli,kanban,monoco,task-management,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Groupware
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sse-starlette>=1.6.0
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Requires-Dist: watchdog>=6.0.0
+Description-Content-Type: text/markdown
+
+# Monoco Toolkit
+
+[![Version](https://img.shields.io/pypi/v/monoco-toolkit)](https://pypi.org/project/monoco-toolkit/)
+[![License](https://img.shields.io/github/license/IndenScale/Monoco)](LICENSE)
+
+> **The Operating System for Agentic Engineering.**
+>
+> Ground your AI Agents into deterministic workflows. Turn vague "chats" into structured, validatable, and shippable engineering units.
+
+---
+
+## ⚡️ Why Monoco?
+
+In the era of LLMs, the bottleneck isn't **intelligence**—it's **control**.
+
+Generating code is easy. Managing the lifecycle of thousands of agent-generated tasks, validating their outputs, and maintaining a coherent project state is hard. **Monoco** is the missing control plane that bridges the gap between raw AI velocity and strict engineering rigor.
+
+Monoco handles the **"BizOps Logic"** of your development process, allowing you to orchestrate human and AI labor within a unified, version-controlled environment.
+
+## 🌟 Core Features
+
+### 1. Issue as Code (IaaC)
+
+Treat your project management like your code.
+
+- **Markdown Native**: All tasks (Epics, Features, Chores) are stored as structured Markdown files in your repository.
+- **Git Backed**: Version control your roadmap. Review changes to requirements via Pull Requests.
+- **Universal Context**: Provides a standardized, hallucination-free state representation for AI Agents.
+
+### 2. The Agent Cockpit (VS Code Extension)
+
+Stop context switching. Manage your entire agentic workflow directly inside your editor.
+
+- **Native Kanban Board**: Visualize and drag-and-drop tasks without leaving VS Code.
+- **Hierarchical Tree View**: Drill down from high-level Epics to atomic Implementation Tasks.
+- **Agent Integration**: Bind specific Agent Providers (Gemini, Claude, etc.) to specific tasks.
+
+### 3. Traceable Execution
+
+- **Deterministic State Machine**: Every task follows a strict lifecycle (Proposed -> Approved -> Doing -> Review -> Done).
+- **Audit Trails**: Agents log their actions and decisions directly into the task file.
+- **Sanity Checks**: Built-in linters ensure your task definitions are complete and valid before execution.
+
+## 🚀 Quick Start
+
+### Installation
+
+Monoco is available as a Python CLI tool.
+
+```bash
+pip install monoco-toolkit
+```
+
+### Initialization
+
+Turn any directory into a Monoco workspace.
+
+```bash
+monoco init
+```
+
+### Workflow
+
+1.  **Plan**: Create a new feature request.
+    ```bash
+    monoco issue create feature -t "Implement Dark Mode"
+    ```
+2.  **Start**: Create a feature branch automatically.
+    ```bash
+    monoco issue start FEAT-001 --branch
+    ```
+3.  **Code & Sync**: Track modified files automatically.
+    ```bash
+    monoco issue sync-files
+    ```
+4.  **Visualize**: Open the board in VS Code or via CLI.
+    ```bash
+    # Starts the local server
+    monoco serve
+    ```
+
+## 📦 Extension for VS Code
+
+The **Monoco VS Code Extension** is the primary visual interface for the toolkit.
+
+- **Install from Marketplace**: Search for `Monoco`.
+- **Keybinding**: `Cmd+Shift+P` -> `Monoco: Open Kanban Board`.
+
+## 🛠️ Tech Stack & Architecture
+
+- **Core**: Python (CLI & Logic Layer)
+- **Extension**: TypeScript (VS Code Client & LSP)
+- **Data**: Local Filesystem (Markdown/YAML)
+
+## 🤝 Contributing
+
+Monoco is designed for the community. We welcome contributions to both the core CLI and the VS Code extension.
+
+## 📄 License
+
+MIT © [IndenScale](https://github.com/IndenScale)