better-notion 1.6.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

better_notion/_cli/docs/base.py

@@ -138,6 +138,7 @@ class Command:
         workflow: Which workflow this command belongs to
         when_to_use: When this command should be used
         error_recovery: Error handling strategies
+        subcommands: Dict of subcommand name -> subcommand documentation
     """
 
     name: str
@@ -147,10 +148,11 @@ class Command:
     workflow: str | None = None
     when_to_use: list[str] = field(default_factory=list)
     error_recovery: dict[str, dict[str, Any]] = field(default_factory=dict)
+    subcommands: dict[str, dict[str, Any]] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
-        return {
+        result = {
             "name": self.name,
             "purpose": self.purpose,
             "description": self.description,
@@ -160,6 +162,12 @@ class Command:
             "error_recovery": self.error_recovery,
         }
 
+        # Add subcommands if present
+        if self.subcommands:
+            result["subcommands"] = self.subcommands
+
+        return result
+
 
 @dataclass
 class Schema:

better_notion/plugins/official/agents.py

@@ -169,22 +169,93 @@ class AgentsPlugin(CombinedPluginInterface):
                                             "state": "already_initialized",
                                             "description": "Agents workspace already exists in this page",
                                         },
+                                        "hierarchy": {
+                                            "description": "Agents workflow hierarchy",
+                                            "levels": [
+                                                {
+                                                    "level": 1,
+                                                    "entity": "Organization",
+                                                    "database": "organizations",
+                                                    "required_before": ["Projects"]
+                                                },
+                                                {
+                                                    "level": 2,
+                                                    "entity": "Project",
+                                                    "database": "projects",
+                                                    "required_before": ["Versions", "Tasks"],
+                                                    "requires": ["Organization"]
+                                                },
+                                                {
+                                                    "level": 3,
+                                                    "entity": "Version",
+                                                    "database": "versions",
+                                                    "required_before": ["Tasks"],
+                                                    "requires": ["Project"]
+                                                },
+                                                {
+                                                    "level": 4,
+                                                    "entity": "Task",
+                                                    "database": "tasks",
+                                                    "requires": ["Version"]
+                                                }
+                                            ]
+                                        },
                                         "next_steps": [
                                             {
-                                                "action": "query_tasks",
-                                                "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
-                                                "purpose": "List all tasks in workspace",
+                                                "action": "check_organizations",
+                                                "command": "notion agents orgs list",
+                                                "purpose": "Check if organizations exist",
+                                                "why": "Organizations are the starting point - create them first"
+                                            },
+                                            {
+                                                "action": "create_organization",
+                                                "command": "notion agents orgs create --name 'Organization Name'",
+                                                "purpose": "Create a new organization",
+                                                "when": "If no organizations exist",
+                                                "examples": [
+                                                    "notion agents orgs create --name 'WareflowX'",
+                                                    "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'"
+                                                ]
+                                            },
+                                            {
+                                                "action": "create_project",
+                                                "command": "notion agents projects create --org 'Org Name' --name 'Project Name'",
+                                                "purpose": "Create a project in an organization",
+                                                "requires": ["organization_exists"],
+                                                "examples": [
+                                                        "notion agents projects create --org 'WareflowX' --name 'Website Redesign'"
+                                                ]
+                                            },
+                                            {
+                                                "action": "create_version",
+                                                "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
+                                                "purpose": "Create a version in a project",
+                                                "requires": ["project_exists"],
                                             },
                                             {
                                                 "action": "create_task",
-                                                "description": "To create a new task, use pages create with Version relation",
+                                                "command": "notion agents tasks create --version 'v1.0.0' --name 'Task Name'",
+                                                "purpose": "Create a task in a version",
+                                                "requires": ["version_exists"],
                                             },
                                         ],
                                         "capabilities": [
+                                            "create_organizations",
+                                            "create_projects",
+                                            "create_versions",
                                             "create_tasks",
-                                            "manage_versions",
-                                            "track_projects",
+                                            "manage_ideas",
+                                            "track_work_issues",
+                                            "manage_incidents",
                                         ],
+                                        "quick_reference": {
+                                            "lifecycle": "Organization → Project → Version → Task",
+                                            "create_org": "notion agents orgs create --name NAME",
+                                            "list_orgs": "notion agents orgs list",
+                                            "create_project": "notion agents projects create --org ORG --name NAME",
+                                            "create_version": "notion agents versions create --project PROJECT --name VERSION",
+                                            "create_task": "notion agents tasks create --version VERSION --name TASK",
+                                        }
                                     }
                                 )
                         except Exception:
@@ -212,40 +283,107 @@ class AgentsPlugin(CombinedPluginInterface):
                                 "description": "Agents workspace ready for task management",
                                 "workspace_name": workspace_name,
                             },
+                            "hierarchy": {
+                                "description": "Agents workflow hierarchy - follow this order",
+                                "lifecycle": "Organization → Project → Version → Task",
+                                "levels": [
+                                    {
+                                        "level": 1,
+                                        "entity": "Organization",
+                                        "database": "organizations",
+                                        "command": "notion agents orgs create --name 'Org Name'",
+                                        "next": "Projects"
+                                    },
+                                    {
+                                        "level": 2,
+                                        "entity": "Project",
+                                        "database": "projects",
+                                        "command": "notion agents projects create --org 'Org' --name 'Project'",
+                                        "requires": ["Organization"],
+                                        "next": "Versions"
+                                    },
+                                    {
+                                        "level": 3,
+                                        "entity": "Version",
+                                        "database": "versions",
+                                        "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
+                                        "requires": ["Project"],
+                                        "next": "Tasks"
+                                    },
+                                    {
+                                        "level": 4,
+                                        "entity": "Task",
+                                        "database": "tasks",
+                                        "command": "notion agents tasks create --version 'v1.0.0' --name 'Task'",
+                                        "requires": ["Version"]
+                                    }
+                                ]
+                            },
                             "next_steps": [
                                 {
-                                    "command": "agents info --parent-page " + parent_page_id,
-                                    "purpose": "View workspace status and database IDs",
-                                    "when": "To verify workspace setup",
+                                    "action": "first_create_organization",
+                                    "priority": 1,
+                                    "command": "notion agents orgs create --name 'Your Organization Name'",
+                                    "purpose": "Create your first organization (required before projects)",
+                                    "why": "Organizations are the top-level entity - all projects belong to an organization",
+                                    "examples": [
+                                        "notion agents orgs create --name 'WareflowX'",
+                                        "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'"
+                                    ]
                                 },
                                 {
-                                    "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
-                                    "purpose": "List all tasks in workspace",
-                                    "when": "To see existing tasks",
+                                    "action": "then_create_project",
+                                    "priority": 2,
+                                    "command": "notion agents projects create --org 'Org Name' --name 'Project Name'",
+                                    "purpose": "Create a project in the organization",
+                                    "requires": ["organization_exists"],
+                                },
+                                {
+                                    "action": "then_create_version",
+                                    "priority": 3,
+                                    "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
+                                    "purpose": "Create a version in the project",
+                                    "requires": ["project_exists"],
                                 },
-                            ],
-                            "capabilities": [
-                                "create_tasks",
-                                "manage_versions",
-                                "track_projects",
-                                "manage_ideas",
-                                "track_incidents",
-                            ],
-                            "common_workflows": [
                                 {
-                                    "name": "create_organization",
-                                    "description": "Create a new organization in the workspace",
-                                    "command": f"notion pages create --parent {database_ids.get('organizations', 'ORGANIZATIONS_DB_ID')} --title 'Organization Name'",
+                                    "action": "then_create_tasks",
+                                    "priority": 4,
+                                    "command": "notion agents tasks create --version 'v1.0.0' --name 'Task Name'",
+                                    "purpose": "Create tasks in the version",
+                                    "requires": ["version_exists"],
                                 },
                                 {
-                                    "name": "create_task",
-                                    "description": "Create a task in the workspace",
-                                    "steps": [
-                                        f"agents info --parent-page {parent_page_id}",
-                                        f"notion pages create --parent {database_ids.get('tasks', 'TASKS_DB_ID')} --title 'Task Name' --properties '{{\"Status\": \"Todo\", \"Version\": \"VERSION_ID\"}}'",
-                                    ],
+                                    "action": "verify_setup",
+                                    "command": "agents info --parent-page " + parent_page_id,
+                                    "purpose": "View workspace status and database IDs",
+                                    "when": "Anytime to verify setup",
                                 },
                             ],
+                            "capabilities": [
+                                "create_organizations",
+                                "create_projects",
+                                "create_versions",
+                                "create_tasks",
+                                "manage_ideas",
+                                "track_work_issues",
+                                "manage_incidents",
+                            ],
+                            "quick_start": {
+                                "description": "Quick start guide - create your first workflow",
+                                "steps": [
+                                    "1. Create organization: notion agents orgs create --name 'WareflowX'",
+                                    "2. Create project: notion agents projects create --org 'WareflowX' --name 'Website Redesign'",
+                                    "3. Create version: notion agents versions create --project 'Website Redesign' --name 'v1.0.0'",
+                                    "4. Create task: notion agents tasks create --version 'v1.0.0' --name 'Fix login bug'"
+                                ]
+                            },
+                            "quick_reference": {
+                                "list_orgs": "notion agents orgs list",
+                                "list_projects": "notion agents projects list",
+                                "list_versions": "notion agents versions list --project 'Project'",
+                                "list_tasks": "notion agents tasks list --version 'v1.0.0'",
+                                "find_next_task": "notion agents tasks next --version 'v1.0.0'"
+                            }
                         }
                     )
 

better_notion/plugins/official/agents_schema.py

@@ -5,6 +5,15 @@ system that AI agents can consume to understand how to work with the system.
 
 This is the SINGLE SOURCE OF TRUTH for agents documentation. All other
 documentation (CLI help, website, etc.) should be derived from this schema.
+
+IMPORTANT - Command signatures use IDs not names:
+- Organization creation: --name (name), --slug (optional)
+- Project creation: --name, --org-id (requires organization PAGE ID)
+- Version creation: --name, --project-id (requires project PAGE ID)
+- Task creation: --title, --version-id (requires version PAGE ID)
+
+You must get entity IDs from previous command responses before creating
+child entities.
 """
 
 from better_notion._cli.docs.base import (
@@ -15,6 +24,172 @@ from better_notion._cli.docs.base import (
     WorkflowStep,
 )
 
+# =============================================================================
+# DATABASE SCHEMAS
+# =============================================================================
+
+ORGANIZATIONS_DB_SCHEMA = {
+    "title": "Organizations",
+    "property_types": {
+        "Name": {
+            "type": "title",
+            "required": True,
+            "description": "Organization name"
+        },
+        "Slug": {
+            "type": "rich_text",
+            "required": False,
+            "description": "URL-friendly identifier"
+        },
+        "Status": {
+            "type": "select",
+            "required": False,
+            "options": ["Active", "Inactive"],
+            "default": "Active"
+        },
+        "Website": {
+            "type": "url",
+            "required": False,
+            "description": "Organization website URL"
+        }
+    },
+    "example_creation": {
+        "command": "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'",
+        "properties": {
+            "Name": "WareflowX",
+            "Slug": "wareflowx",
+            "Status": "Active"
+        }
+    }
+}
+
+PROJECTS_DB_SCHEMA = {
+    "title": "Projects",
+    "property_types": {
+        "Name": {
+            "type": "title",
+            "required": True,
+            "description": "Project name"
+        },
+        "Organization": {
+            "type": "relation",
+            "required": True,
+            "target": "Organizations",
+            "description": "Organization this project belongs to (requires org PAGE ID)"
+        },
+        "Status": {
+            "type": "select",
+            "required": False,
+            "options": ["Active", "On Hold", "Completed", "Archived"],
+            "default": "Active"
+        },
+        "Description": {
+            "type": "rich_text",
+            "required": False,
+            "description": "Project description"
+        }
+    },
+    "example_creation": {
+        "command": "notion agents projects create --name 'Website Redesign' --org-id ORG_PAGE_ID",
+        "properties": {
+            "Name": "Website Redesign",
+            "Organization": "ORG_PAGE_ID",
+            "Status": "Active"
+        },
+        "note": "ORG_PAGE_ID comes from 'notion agents orgs create' response (id field)"
+    }
+}
+
+VERSIONS_DB_SCHEMA = {
+    "title": "Versions",
+    "property_types": {
+        "Name": {
+            "type": "title",
+            "required": True,
+            "description": "Version name (e.g., v1.0.0)"
+        },
+        "Project": {
+            "type": "relation",
+            "required": True,
+            "target": "Projects",
+            "description": "Project this version belongs to (requires project PAGE ID)"
+        },
+        "Status": {
+            "type": "select",
+            "required": False,
+            "options": ["Planning", "In Progress", "Released", "Archived"],
+            "default": "Planning"
+        },
+        "Release Date": {
+            "type": "date",
+            "required": False,
+            "description": "Planned or actual release date"
+        }
+    },
+    "example_creation": {
+        "command": "notion agents versions create --name 'v1.0.0' --project-id PROJECT_PAGE_ID",
+        "properties": {
+            "Name": "v1.0.0",
+            "Project": "PROJECT_PAGE_ID",
+            "Status": "Planning"
+        },
+        "note": "PROJECT_PAGE_ID comes from 'notion agents projects create' response (id field)"
+    }
+}
+
+TASKS_DB_SCHEMA = {
+    "title": "Tasks",
+    "property_types": {
+        "Name": {
+            "type": "title",
+            "required": True,
+            "description": "Task name"
+        },
+        "Status": {
+            "type": "select",
+            "required": True,
+            "options": ["Backlog", "Claimed", "In Progress", "Completed", "Cancelled"],
+            "default": "Backlog"
+        },
+        "Version": {
+            "type": "relation",
+            "required": True,
+            "target": "Versions",
+            "description": "Version this task belongs to (requires version PAGE ID)"
+        },
+        "Dependencies": {
+            "type": "relation",
+            "required": False,
+            "target": "Tasks",
+            "dual_property": "Dependent Tasks",
+            "description": "Tasks that must complete before this task"
+        },
+        "Dependent Tasks": {
+            "type": "relation",
+            "required": False,
+            "target": "Tasks",
+            "dual_property": "Dependencies",
+            "description": "Tasks blocked by this task"
+        },
+        "Priority": {
+            "type": "select",
+            "required": False,
+            "options": ["Low", "Medium", "High", "Critical"],
+            "default": "Medium"
+        }
+    },
+    "example_creation": {
+        "command": "notion agents tasks create --title 'Fix login bug' --version-id VERSION_PAGE_ID",
+        "properties": {
+            "Name": "Fix login bug",
+            "Status": "Backlog",
+            "Version": "VERSION_PAGE_ID",
+            "Priority": "High"
+        },
+        "note": "VERSION_PAGE_ID comes from 'notion agents versions create' response (id field)"
+    }
+}
+
 # =============================================================================
 # CONCEPTS
 # =============================================================================
@@ -50,25 +225,57 @@ WORKSPACE_CONCEPT = Concept(
     },
 )
 
+ORGANIZATION_CONCEPT = Concept(
+    name="organization",
+    description=(
+        "An organization represents a company, team, or entity that owns projects. "
+        "Organizations are the top-level entities in the agents workflow hierarchy."
+    ),
+    properties={
+        "database_schema": ORGANIZATIONS_DB_SCHEMA,
+        "creation": {
+            "command": "notion agents orgs create --name 'Org Name' --slug 'org-slug'",
+            "returns": "JSON with 'id' field containing organization PAGE ID",
+            "required_flags": {"--name": "Organization name (required)"},
+            "optional_flags": {
+                "--slug": "URL-friendly identifier (optional)",
+                "--description": "Organization description (optional)",
+                "--repository-url": "Git repository URL (optional)",
+                "--status": "Active or Inactive (default: Active)"
+            }
+        },
+        "listing": {
+            "command": "notion agents orgs list",
+            "description": "List all organizations in workspace",
+            "returns": "JSON array of organizations with id, name, slug, status"
+        }
+    },
+    relationships={
+        "Projects": "One-to-many - organization contains multiple projects",
+        "description": "All projects must belong to an organization",
+    },
+)
+
 TASK_CONCEPT = Concept(
     name="task",
     description=(
         "A task represents a unit of work that needs to be completed as part of "
-        "a project version. Tasks have states (Todo, In Progress, Done, Cancelled) "
+        "a project version. Tasks have states (Backlog, Claimed, In Progress, Completed) "
         "and can depend on other tasks."
     ),
     properties={
         "required_properties": {
             "Title": "Task name (title property)",
-            "Status": "Current state: Todo, In Progress, Done, Cancelled",
-            "Version": "Relation to Version database (required)",
+            "Status": "Current state: Backlog, Claimed, In Progress, Completed, Cancelled",
+            "Version": "Relation to Version database (requires version PAGE ID)",
         },
         "optional_properties": {
-            "Target Version": "Version where task should be implemented",
-            "Dependencies": "Other tasks this task depends on",
-            "Dependent Tasks": "Tasks that depend on this task",
+            "Type": "Task type: New Feature, Bug Fix, Refactor, Documentation, Testing, Other",
+            "Priority": "Low, Medium, High, Critical",
+            "Dependencies": "Other tasks this task depends on (comma-separated task IDs)",
+            "Estimated Hours": "Time estimate in hours",
         },
-        "workflow": "Todo → In Progress → Done",
+        "workflow": "Backlog → Claimed → In Progress → Completed",
     },
     relationships={
         "Version": "Required - each task must belong to one version",
@@ -85,13 +292,20 @@ PROJECT_CONCEPT = Concept(
     ),
     properties={
         "required_properties": {
-            "Title": "Project name",
-            "Organization": "Relation to organization (required)",
+            "Name": "Project name",
+            "Organization ID": "Organization PAGE ID from 'agents orgs create' response",
+        },
+        "optional_properties": {
+            "Slug": "URL-friendly identifier",
+            "Description": "Project description",
+            "Repository": "Git repository URL",
+            "Tech Stack": "Comma-separated technologies",
+            "Role": "Project role: Developer, Designer, PM, QA, DevOps (default: Developer)",
         },
         "contains": ["Versions", "Tasks", "Ideas", "Work Issues", "Incidents"],
     },
     relationships={
-        "Organization": "Required - each project belongs to one organization",
+        "Organization": "Required - each project belongs to one organization (via org-id)",
         "Versions": "One-to-many - project contains multiple versions",
     },
 )
@@ -104,14 +318,20 @@ VERSION_CONCEPT = Concept(
     ),
     properties={
         "required_properties": {
-            "Title": "Version name (e.g., v1.0.0)",
-            "Project": "Relation to project (required)",
+            "Name": "Version name (e.g., v1.0.0)",
+            "Project ID": "Project PAGE ID from 'agents projects create' response",
+        },
+        "optional_properties": {
+            "Status": "Planning, In Progress, Released, Archived (default: Planning)",
+            "Type": "Major, Minor, Patch, Hotfix (default: Minor)",
+            "Branch": "Git branch name",
+            "Progress": "Progress percentage 0-100 (default: 0)",
         },
         "contains": ["Tasks"],
         "examples": ["v1.0.0", "v1.1.0", "v2.0.0-beta", "sprint-1"],
     },
     relationships={
-        "Project": "Required - each version belongs to one project",
+        "Project": "Required - each version belongs to one project (via project-id)",
         "Tasks": "One-to-many - version contains multiple tasks",
     },
 )
@@ -198,6 +418,122 @@ INITIALIZE_WORKSPACE = Workflow(
     },
 )
 
+CREATE_ORGANIZATION_WORKFLOW = Workflow(
+    name="create_organization",
+    description="Create a new organization in the agents workspace",
+    steps=[
+        WorkflowStep(
+            description="Verify workspace is initialized",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Get Organizations database ID and verify workspace exists",
+        ),
+        WorkflowStep(
+            description="Create organization using agents command",
+            command="notion agents orgs create --name 'Org Name' --slug 'org-slug'",
+            purpose="Create organization with proper properties",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'",
+    ],
+    prerequisites=["workspace_initialized"],
+    error_recovery={
+        "workspace_not_found": {
+            "message": "No workspace detected in page",
+            "solution": "Run 'agents init --parent-page PAGE_ID' first to create workspace",
+        },
+        "missing_name": {
+            "message": "Organization name is required",
+            "solution": "Always specify --name flag when creating organization",
+        },
+    },
+)
+
+CREATE_PROJECT_WORKFLOW = Workflow(
+    name="create_project",
+    description="Create a new project in an organization",
+    steps=[
+        WorkflowStep(
+            description="Verify workspace is initialized",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Get database IDs and verify workspace exists",
+        ),
+        WorkflowStep(
+            description="List organizations to get organization ID",
+            command="notion agents orgs list",
+            purpose="Get the organization PAGE ID from the response",
+        ),
+        WorkflowStep(
+            description="Create project with organization ID",
+            command="notion agents projects create --name 'Project Name' --org-id ORG_PAGE_ID",
+            purpose="Create project with Organization relation (requires org PAGE ID, not name)",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion agents orgs list",
+        "notion agents projects create --name 'Website Redesign' --org-id ORG_PAGE_ID",
+    ],
+    prerequisites=["workspace_initialized", "organization_exists"],
+    error_recovery={
+        "workspace_not_found": {
+            "message": "No workspace detected in page",
+            "solution": "Run 'agents init --parent-page PAGE_ID' first to create workspace",
+        },
+        "organization_not_found": {
+            "message": "Organization ID not found",
+            "solution": "Run 'agents orgs list' to get valid organization IDs, or create org first with 'agents orgs create --name NAME'",
+        },
+        "missing_org_id": {
+            "message": "Project requires --org-id (organization PAGE ID), not name",
+            "solution": "Use --org-id with the ID from 'agents orgs list' response",
+        },
+    },
+)
+
+CREATE_VERSION_WORKFLOW = Workflow(
+    name="create_version",
+    description="Create a new version in a project",
+    steps=[
+        WorkflowStep(
+            description="Verify workspace is initialized",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Get database IDs and verify workspace exists",
+        ),
+        WorkflowStep(
+            description="List projects to get project ID",
+            command="notion agents projects list",
+            purpose="Get the project PAGE ID from the response",
+        ),
+        WorkflowStep(
+            description="Create version with project ID",
+            command="notion agents versions create --name 'v1.0.0' --project-id PROJECT_PAGE_ID",
+            purpose="Create version with Project relation (requires project PAGE ID, not name)",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion agents projects list",
+        "notion agents versions create --name 'v1.0.0' --project-id PROJECT_PAGE_ID",
+    ],
+    prerequisites=["workspace_initialized", "organization_exists", "project_exists"],
+    error_recovery={
+        "workspace_not_found": {
+            "message": "No workspace detected in page",
+            "solution": "Run 'agents init --parent-page PAGE_ID' first to create workspace",
+        },
+        "project_not_found": {
+            "message": "Project ID not found",
+            "solution": "Run 'agents projects list' to get valid project IDs, or create project first with 'agents projects create --name NAME --org-id ORG_ID'",
+        },
+        "missing_project_id": {
+            "message": "Version requires --project-id (project PAGE ID), not name",
+            "solution": "Use --project-id with the ID from 'agents projects list' response",
+        },
+    },
+)
+
 CREATE_TASK_WORKFLOW = Workflow(
     name="create_task",
     description="Create a new task in the agents workflow system",
@@ -208,18 +544,20 @@ CREATE_TASK_WORKFLOW = Workflow(
             purpose="Get database IDs and verify workspace exists",
         ),
         WorkflowStep(
-            description="Identify target Version",
-            purpose="Tasks must belong to a Version (required relation)",
+            description="List versions to get version ID",
+            command="notion agents versions list",
+            purpose="Get the version PAGE ID from the response",
         ),
         WorkflowStep(
-            description="Create task page with proper properties",
-            command="notion pages create --parent TASKS_DB_ID --title 'Task Name' --properties '{...}'",
-            purpose="Create task with Status and Version relation",
+            description="Create task with version ID",
+            command="notion agents tasks create --title 'Task Name' --version-id VERSION_PAGE_ID",
+            purpose="Create task with Version relation (requires version PAGE ID, not name)",
         ),
     ],
     commands=[
         "agents info --parent-page PAGE_ID",
-        "notion pages create --parent TASKS_DB_ID --title 'Task' --properties '{\"Status\": \"Todo\", \"Version\": \"VERSION_ID\"}'",
+        "notion agents versions list",
+        "notion agents tasks create --title 'Fix login bug' --version-id VERSION_PAGE_ID",
     ],
     prerequisites=["workspace_initialized"],
     error_recovery={
@@ -227,9 +565,13 @@ CREATE_TASK_WORKFLOW = Workflow(
             "message": "No workspace detected in page",
             "solution": "Run 'agents init' first to create workspace",
         },
-        "missing_version_relation": {
-            "message": "Task must have a Version relation",
-            "solution": "Always specify Version property when creating task",
+        "version_not_found": {
+            "message": "Version ID not found",
+            "solution": "Run 'agents versions list' to get valid version IDs, or create version first with 'agents versions create --name NAME --project-id PROJECT_ID'",
+        },
+        "missing_version_id": {
+            "message": "Task requires --version-id (version PAGE ID), not name",
+            "solution": "Use --version-id with the ID from 'agents versions list' response",
         },
     },
 )
@@ -307,13 +649,211 @@ INFO_COMMAND = Command(
     ],
 )
 
+# =============================================================================
+# SUBCOMMANDS
+# =============================================================================
+
+# ORGS_SUBCOMMAND documents the agents orgs commands
+ORGS_COMMAND = Command(
+    name="orgs",
+    purpose="Organizations management - top-level entities in workflow hierarchy",
+    description=(
+        "Organizations are the starting point for all projects. "
+        "Every project must belong to an organization."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all organizations in workspace",
+            "usage": "notion agents orgs list",
+            "output": "Returns JSON array with organization objects containing id, name, slug, status"
+        },
+        "get": {
+            "purpose": "Get organization by ID",
+            "usage": "notion agents orgs get ORG_PAGE_ID",
+            "output": "Returns organization details"
+        },
+        "create": {
+            "purpose": "Create a new organization",
+            "usage": "notion agents orgs create --name NAME [--slug SLUG] [--description DESC] [--repository-url URL] [--status STATUS]",
+            "required_flags": {
+                "--name": "Organization name (required)"
+            },
+            "optional_flags": {
+                "--slug": "URL-friendly identifier (optional)",
+                "--description": "Organization description (optional)",
+                "--repository-url": "Git repository URL (optional)",
+                "--status": "Active or Inactive (default: Active)"
+            },
+            "returns": "JSON with 'id' field containing organization PAGE ID (needed for creating projects)",
+            "examples": [
+                "notion agents orgs create --name 'WareflowX'",
+                "notion agents orgs create --name 'WareflowX' --slug 'wareflowx' --status 'Active'"
+            ]
+        }
+    }
+)
+
+# PROJECTS_SUBCOMMAND documents the agents projects commands
+PROJECTS_COMMAND = Command(
+    name="projects",
+    purpose="Projects management - belongs to organizations",
+    description=(
+        "Projects represent software development efforts. "
+        "Every project must belong to an organization (requires org PAGE ID)."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all projects (optionally filtered by organization)",
+            "usage": "notion agents projects list [--org-id ORG_PAGE_ID]",
+            "output": "Returns JSON array with project objects containing id, name, slug, status, organization_id"
+        },
+        "get": {
+            "purpose": "Get project by ID",
+            "usage": "notion agents projects get PROJECT_PAGE_ID",
+            "output": "Returns project details"
+        },
+        "create": {
+            "purpose": "Create a new project in an organization",
+            "usage": "notion agents projects create --name NAME --org-id ORG_PAGE_ID [--slug SLUG] [--description DESC] [--repository REPO] [--tech-stack STACK]",
+            "required_flags": {
+                "--name": "Project name (required)",
+                "--org-id": "Organization PAGE ID (required) - use ID from 'agents orgs list' or 'agents orgs create' response"
+            },
+            "optional_flags": {
+                "--slug": "URL-friendly identifier (optional)",
+                "--description": "Project description (optional)",
+                "--repository": "Git repository URL (optional)",
+                "--tech-stack": "Comma-separated tech stack (optional)",
+                "--status": "Active, On Hold, Completed, Archived (default: Active)",
+                "--role": "Developer, Designer, PM, QA, DevOps (default: Developer)"
+            },
+            "returns": "JSON with 'id' field containing project PAGE ID (needed for creating versions)",
+            "examples": [
+                "notion agents projects create --name 'Website Redesign' --org-id org_12345"
+            ],
+            "note": "IMPORTANT: Use --org-id with organization PAGE ID, not organization name"
+        }
+    }
+)
+
+# VERSIONS_SUBCOMMAND documents the agents versions commands
+VERSIONS_COMMAND = Command(
+    name="versions",
+    purpose="Versions management - releases and milestones",
+    description=(
+        "Versions represent releases or milestones. "
+        "Every version must belong to a project (requires project PAGE ID)."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all versions (optionally filtered by project)",
+            "usage": "notion agents versions list [--project-id PROJECT_PAGE_ID]",
+            "output": "Returns JSON array with version objects containing id, name, status, type, project_id"
+        },
+        "get": {
+            "purpose": "Get version by ID",
+            "usage": "notion agents versions get VERSION_PAGE_ID",
+            "output": "Returns version details"
+        },
+        "create": {
+            "purpose": "Create a new version in a project",
+            "usage": "notion agents versions create --name NAME --project-id PROJECT_PAGE_ID [--type TYPE] [--status STATUS]",
+            "required_flags": {
+                "--name": "Version name e.g. v1.0.0 (required)",
+                "--project-id": "Project PAGE ID (required) - use ID from 'agents projects list' or 'agents projects create' response"
+            },
+            "optional_flags": {
+                "--status": "Planning, In Progress, Released, Archived (default: Planning)",
+                "--type": "Major, Minor, Patch, Hotfix (default: Minor)",
+                "--branch": "Git branch name (optional)",
+                "--progress": "Progress percentage 0-100 (default: 0)"
+            },
+            "returns": "JSON with 'id' field containing version PAGE ID (needed for creating tasks)",
+            "examples": [
+                "notion agents versions create --name 'v1.0.0' --project-id proj_12345"
+            ],
+            "note": "IMPORTANT: Use --project-id with project PAGE ID, not project name"
+        }
+    }
+)
+
+# TASKS_SUBCOMMAND documents the agents tasks commands
+TASKS_COMMAND = Command(
+    name="tasks",
+    purpose="Tasks management - units of work in versions",
+    description=(
+        "Tasks represent work items. Every task must belong to a version (requires version PAGE ID). "
+        "Tasks can have dependencies on other tasks."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all tasks (optionally filtered by version or status)",
+            "usage": "notion agents tasks list [--version-id VERSION_PAGE_ID] [--status STATUS]",
+            "output": "Returns JSON array with task objects containing id, title, status, type, priority, version_id"
+        },
+        "get": {
+            "purpose": "Get task by ID",
+            "usage": "notion agents tasks get TASK_PAGE_ID",
+            "output": "Returns task details"
+        },
+        "create": {
+            "purpose": "Create a new task in a version",
+            "usage": "notion agents tasks create --title TITLE --version-id VERSION_PAGE_ID [--type TYPE] [--priority PRIORITY] [--dependencies DEP_IDS]",
+            "required_flags": {
+                "--title": "Task name (required)",
+                "--version-id": "Version PAGE ID (required) - use ID from 'agents versions list' or 'agents versions create' response"
+            },
+            "optional_flags": {
+                "--status": "Backlog, Claimed, In Progress, Completed, Cancelled (default: Backlog)",
+                "--type": "New Feature, Bug Fix, Refactor, Documentation, Testing, Other (default: New Feature)",
+                "--priority": "Low, Medium, High, Critical (default: Medium)",
+                "--dependencies": "Comma-separated dependency task IDs (optional)",
+                "--estimate": "Estimated hours (optional)"
+            },
+            "returns": "JSON with 'id' field containing task PAGE ID",
+            "examples": [
+                "notion agents tasks create --title 'Fix login bug' --version-id ver_12345",
+                "notion agents tasks create --title 'Add feature' --version-id ver_12345 --priority 'High' --type 'New Feature'"
+            ],
+            "note": "IMPORTANT: Use --version-id with version PAGE ID, not version name"
+        },
+        "next": {
+            "purpose": "Find next available task to work on",
+            "usage": "notion agents tasks next [--project-id PROJECT_PAGE_ID]",
+            "description": "Finds tasks with status 'Backlog' or 'Claimed' and no incomplete dependencies",
+            "output": "Returns task object or message if no tasks available"
+        },
+        "claim": {
+            "purpose": "Claim a task (transition to Claimed status)",
+            "usage": "notion agents tasks claim TASK_PAGE_ID",
+            "output": "Returns updated task with agent ID"
+        },
+        "start": {
+            "purpose": "Start working on a task (transition to In Progress)",
+            "usage": "notion agents tasks start TASK_PAGE_ID",
+            "output": "Returns updated task with agent ID",
+            "note": "Will fail if task has incomplete dependencies"
+        },
+        "complete": {
+            "purpose": "Complete a task (transition to Completed)",
+            "usage": "notion agents tasks complete TASK_PAGE_ID [--actual-hours HOURS]",
+            "output": "Returns completed task with actual hours"
+        },
+        "can-start": {
+            "purpose": "Check if a task can start (all dependencies completed)",
+            "usage": "notion agents tasks can-start TASK_PAGE_ID",
+            "output": "Returns boolean and lists incomplete dependencies if any"
+        }
+    }
+)
+
 # =============================================================================
 # COMPLETE SCHEMA
 # =============================================================================
 
 AGENTS_SCHEMA = Schema(
     name="agents",
-    version="1.0.0",
+    version="2.0.0",
     description=(
         "Workflow management system for software development. "
         "Provides complete structure for tracking organizations, projects, "
@@ -321,28 +861,41 @@ AGENTS_SCHEMA = Schema(
     ),
     concepts=[
         WORKSPACE_CONCEPT,
-        TASK_CONCEPT,
+        ORGANIZATION_CONCEPT,
         PROJECT_CONCEPT,
         VERSION_CONCEPT,
+        TASK_CONCEPT,
     ],
     workflows=[
         INITIALIZE_WORKSPACE,
+        CREATE_ORGANIZATION_WORKFLOW,
+        CREATE_PROJECT_WORKFLOW,
+        CREATE_VERSION_WORKFLOW,
         CREATE_TASK_WORKFLOW,
         QUERY_TASKS_WORKFLOW,
     ],
     commands={
         "init": INIT_COMMAND,
         "info": INFO_COMMAND,
+        "orgs": ORGS_COMMAND,
+        "projects": PROJECTS_COMMAND,
+        "versions": VERSIONS_COMMAND,
+        "tasks": TASKS_COMMAND,
     },
     best_practices=[
-        "Always run 'agents info' before database operations to verify workspace state",
+        "Follow the hierarchy: Organization → Project → Version → Task",
+        "Always run 'agents info' before operations to verify workspace state",
         "Use --skip flag to safely check for existing workspaces (prevents duplicates)",
         "Use --reset flag only when you need to recreate workspace (causes data loss)",
-        "Tasks must have a Version relation - always specify Version property",
-        "Check task dependencies before marking tasks as complete",
-        "Projects belong to Organizations - create organization first",
-        "Versions belong to Projects - create project first",
-        "Query tasks by Status to find next available task",
+        "IMPORTANT: Child entities require parent PAGE IDs, not names",
+        "Save the 'id' field from create responses - you need it for creating child entities",
+        "Use 'agents orgs/projects/versions list' to get valid entity IDs",
+        "Create organization before creating projects",
+        "Create project before creating versions",
+        "Create version before creating tasks",
+        "Tasks must have a Version relation (required via --version-id)",
+        "Projects must have an Organization relation (required via --org-id)",
+        "Use 'agents tasks next' to find next available task",
     ],
     examples={
         "initial_setup": """# First time setup
@@ -357,13 +910,71 @@ notion agents init --parent-page PAGE_ID --skip""",
         "force_recreate": """# Delete existing workspace and recreate (WARNING: data loss)
 notion agents init --parent-page PAGE_ID --reset""",
 
-        "query_workspace": """# Get workspace info and database IDs
-notion agents info --parent-page PAGE_ID""",
+        "complete_lifecycle": """# Complete workflow: Org → Project → Version → Task
+# IMPORTANT: Each command returns an ID that the next command needs!
+
+# 1. Create organization - SAVE THE ID from response!
+notion agents orgs create --name "WareflowX" --slug "wareflowx"
+# Response: {id: "org_abc123", "name": "WareflowX", ...}
+# Save: ORG_ID="org_abc123"
+
+# 2. Create project - requires org PAGE ID, not name!
+notion agents projects create --name "Website Redesign" --org-id "org_abc123"
+# Response: {id: "proj_def456", "name": "Website Redesign", ...}
+# Save: PROJECT_ID="proj_def456"
+
+# 3. Create version - requires project PAGE ID, not name!
+notion agents versions create --name "v1.0.0" --project-id "proj_def456"
+# Response: {id: "ver_ghi789", "name": "v1.0.0", ...}
+# Save: VERSION_ID="ver_ghi789"
+
+# 4. Create task - requires version PAGE ID, not name!
+notion agents tasks create --title "Fix login bug" --version-id "ver_ghi789" --priority "High\"""",
+
+        "list_and_filter": """# List all organizations
+notion agents orgs list
+
+# List all projects (unfiltered)
+notion agents projects list
+
+# List all versions (unfiltered)
+notion agents versions list
+
+# List tasks in a specific version
+notion agents tasks list --version-id "ver_ghi789"
+
+# Find next task to work on
+notion agents tasks next""",
+
+        "task_workflow": """# Find a task
+notion agents tasks next
+
+# Claim a task (uses task ID from list or next)
+notion agents tasks claim task_xyz123
+
+# Start working on task (fails if dependencies not complete)
+notion agents tasks start task_xyz123
+
+# Complete task
+notion agents tasks complete task_xyz123 --actual-hours 3.5""",
+
+        "get_entity_by_id": """# Get organization details
+notion agents orgs get org_abc123
+
+# Get project details
+notion agents projects get proj_def456
+
+# Get version details
+notion agents versions get ver_ghi789
+
+# Get task details
+notion agents tasks get task_xyz123""",
+
+        "check_dependencies": """# Check if task can start (all deps complete?)
+notion agents tasks can-start task_xyz123
+# Returns: {can_start: false, incomplete_dependencies: [...]}
 
-        "create_task": """# After workspace is initialized
-notion pages create \\
-  --parent TASKS_DB_ID \\
-  --title "Fix login bug" \\
-  --properties '{"Status": "Todo", "Version": "VERSION_ID"}'""",
+# List tasks with dependencies
+notion agents tasks list --version-id ver_ghi789""",
     },
 )

{better_notion-1.6.0.dist-info → better_notion-1.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 1.6.0
+Version: 1.8.0
 Summary: A high-level Python SDK for the Notion API with developer experience in mind.
 Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
 Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme

{better_notion-1.6.0.dist-info → better_notion-1.8.0.dist-info}/RECORD

@@ -49,7 +49,7 @@ better_notion/_cli/commands/update.py,sha256=NfmijzTpCbVTEY2h0QdcJZXEiGmWkk-iyEt
 better_notion/_cli/commands/users.py,sha256=wpjKCo-HHfpiGsjvLSs8nb2MjZ8nxtppCC0N_OCkz9M,4890
 better_notion/_cli/commands/workspace.py,sha256=f3VQcXZ6lu2QrAxkQyFVb3FVU7LYC8kag6VOUvVEu-c,3671
 better_notion/_cli/docs/__init__.py,sha256=NQ2Wt18dVEE43hw2XZtdM8S3OJ5DHzLTKW20byxxYng,415
-better_notion/_cli/docs/base.py,sha256=xESWiLIaNqK8jCs34_jM1E33oaIv4lwmhJkJh3Lf4RQ,6538
+better_notion/_cli/docs/base.py,sha256=2l-4mR-Ss_jMrT2ZNF0xT-kr-XbbaGg8-ed-Fy62hE0,6837
 better_notion/_cli/docs/formatters.py,sha256=bFZ2WOr7Q1O-Q2uUXWki_88jciqHU39wJeaOc_QqSGc,4261
 better_notion/_cli/docs/registry.py,sha256=D1AyQoUITrs-8r_hP72C6ef1vsEQhOEqV13oBuv3pK0,2281
 better_notion/_cli/utils/__init__.py,sha256=VV2SaZnclN-HMMRIsqgxlBNL2HB4n1AvAfMJJWCoTxo,29
@@ -111,9 +111,9 @@ better_notion/plugins/base.py,sha256=3h9jOZzS--UqmVW3RREtcQ2h1GTWWPUryTencsJKhTM
 better_notion/plugins/loader.py,sha256=zCWsMdJyvZs1IHFm0zjEiqm_l_5jB1Uw4x30Kq8rLS4,9527
 better_notion/plugins/state.py,sha256=jH_tZWvC35hqLO4qwl2Kwq9ziWVavwCEUcCqy3s5wMY,3780
 better_notion/plugins/official/__init__.py,sha256=rPg5vdk1cEANVstMPzxcWmImtsOpdSR40JSml7h1uUk,426
-better_notion/plugins/official/agents.py,sha256=Wc3EK934GEbD3lGrU2ZuVW8K5bNVA1BIGqttk52wIno,40859
+better_notion/plugins/official/agents.py,sha256=OHX-vmEsab8b-tMljXJLOB9YRpq1oG125FTK7mtm23A,50667
 better_notion/plugins/official/agents_cli.py,sha256=8l6e1zJCAT4DdAO-QfdjK_vrrrik3pmrojwakE32ZNY,53048
-better_notion/plugins/official/agents_schema.py,sha256=QDMGzOUEtH2QShIig8g6pS8veeZz6x034RXm6MU2PJQ,14136
+better_notion/plugins/official/agents_schema.py,sha256=NQRAJFoBAXRuxB9_9Eaf-4tVth-1OZh7GjmN56Yp9lA,39867
 better_notion/plugins/official/productivity.py,sha256=_-whP4pYA4HufE1aUFbIdhrjU-O9njI7xUO_Id2M1J8,8726
 better_notion/plugins/official/agents_sdk/__init__.py,sha256=luQBzZLsJ7fC5U0jFu8dfzMviiXj2SBZXcTohM53wkQ,725
 better_notion/plugins/official/agents_sdk/managers.py,sha256=0zMZPu63zhdyqiudO2gKsmM3YOJh0nFAR9FrMlwkV2A,31186
@@ -132,8 +132,8 @@ better_notion/utils/agents/rbac.py,sha256=8ZA8Y7wbOiVZDbpjpH7iC35SZrZ0jl4fcJ3xWC
 better_notion/utils/agents/schemas.py,sha256=eHfGhY90FAPXA3E8qE6gP75dgNzn-9z5Ju1FMwBKnQQ,22120
 better_notion/utils/agents/state_machine.py,sha256=xUBEeDTbU1Xq-rsRo2sbr6AUYpYrV9DTHOtZT2cWES8,6699
 better_notion/utils/agents/workspace.py,sha256=nS7BNa0-RFCxeAKa0inmBZcPfRKTMB11pi9OW4WzvQ4,15915
-better_notion-1.6.0.dist-info/METADATA,sha256=leiPUN0D9auHnDVpw5hos7gPAoxwsEwJVp4xv8vVunk,11096
-better_notion-1.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-better_notion-1.6.0.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
-better_notion-1.6.0.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
-better_notion-1.6.0.dist-info/RECORD,,
+better_notion-1.8.0.dist-info/METADATA,sha256=6HwsgB9jczxjDz6qehycler3WfqBs2MLbUz89VWnDYg,11096
+better_notion-1.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+better_notion-1.8.0.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
+better_notion-1.8.0.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
+better_notion-1.8.0.dist-info/RECORD,,