better-notion 1.6.0__py3-none-any.whl → 1.7.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

@@ -15,6 +15,175 @@ 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 pages create --parent ORG_DB_ID --title '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"
+        },
+        "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 pages create --parent PROJECTS_DB_ID --title 'Website Redesign'",
+        "properties": {
+            "Name": "Website Redesign",
+            "Organization": "ORG_PAGE_ID",
+            "Status": "Active"
+        }
+    }
+}
+
+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"
+        },
+        "Status": {
+            "type": "select",
+            "required": False,
+            "options": ["Planned", "In Progress", "Released", "Archived"],
+            "default": "Planned"
+        },
+        "Release Date": {
+            "type": "date",
+            "required": False,
+            "description": "Planned or actual release date"
+        }
+    },
+    "example_creation": {
+        "command": "notion pages create --parent VERSIONS_DB_ID --title 'v1.0.0'",
+        "properties": {
+            "Name": "v1.0.0",
+            "Project": "PROJECT_PAGE_ID",
+            "Status": "Planned"
+        }
+    }
+}
+
+TASKS_DB_SCHEMA = {
+    "title": "Tasks",
+    "property_types": {
+        "Name": {
+            "type": "title",
+            "required": True,
+            "description": "Task name"
+        },
+        "Status": {
+            "type": "select",
+            "required": True,
+            "options": ["Todo", "In Progress", "Done", "Cancelled"],
+            "default": "Todo"
+        },
+        "Version": {
+            "type": "relation",
+            "required": True,
+            "target": "Versions",
+            "description": "Version this task belongs to (REQUIRED)"
+        },
+        "Target Version": {
+            "type": "relation",
+            "required": False,
+            "target": "Versions",
+            "description": "Version where task should be implemented"
+        },
+        "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 pages create --parent TASKS_DB_ID --title 'Fix login bug'",
+        "properties": {
+            "Name": "Fix login bug",
+            "Status": "Todo",
+            "Version": "VERSION_PAGE_ID",
+            "Priority": "High"
+        }
+    }
+}
+
 # =============================================================================
 # CONCEPTS
 # =============================================================================
@@ -50,6 +219,36 @@ 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'",
+            "alternative": "notion pages create --parent ORG_DB_ID --title 'Org Name' --properties '{...}'",
+            "required_properties": ["Name"],
+            "property_types": {
+                "Name": "title (required)",
+                "Slug": "rich_text (optional, URL-friendly identifier)",
+                "Status": "select [Active, Inactive] (optional, default: Active)",
+                "Website": "url (optional)"
+            }
+        },
+        "listing": {
+            "command": "notion agents orgs list",
+            "description": "List all organizations in workspace"
+        }
+    },
+    relationships={
+        "Projects": "One-to-many - organization contains multiple projects",
+        "description": "All projects must belong to an organization"
+    },
+)
+
 TASK_CONCEPT = Concept(
     name="task",
     description=(
@@ -198,6 +397,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 find target",
+            command="notion agents orgs list",
+            purpose="Identify which organization the project belongs to",
+        ),
+        WorkflowStep(
+            description="Create project with organization relation",
+            command="notion agents projects create --org 'Org Name/Slug' --name 'Project Name'",
+            purpose="Create project with Organization relation (required)",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion agents orgs list",
+        "notion agents projects create --org 'WareflowX' --name 'Website Redesign'",
+    ],
+    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 not found",
+            "solution": "Create organization first with 'agents orgs create --name NAME'",
+        },
+        "missing_org_relation": {
+            "message": "Project must have Organization relation",
+            "solution": "Always specify --org flag when creating project",
+        },
+    },
+)
+
+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 find target",
+            command="notion agents projects list",
+            purpose="Identify which project the version belongs to",
+        ),
+        WorkflowStep(
+            description="Create version with project relation",
+            command="notion agents versions create --project 'Project Name' --name 'v1.0.0'",
+            purpose="Create version with Project relation (required)",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion agents projects list",
+        "notion agents versions create --project 'Website Redesign' --name 'v1.0.0'",
+    ],
+    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 not found",
+            "solution": "Create project first with 'agents projects create --org ORG --name NAME'",
+        },
+        "missing_project_relation": {
+            "message": "Version must have Project relation",
+            "solution": "Always specify --project flag when creating version",
+        },
+    },
+)
+
 CREATE_TASK_WORKFLOW = Workflow(
     name="create_task",
     description="Create a new task in the agents workflow system",
@@ -307,13 +622,153 @@ 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 list of organizations with their IDs and properties"
+        },
+        "create": {
+            "purpose": "Create a new organization",
+            "usage": "notion agents orgs create --name NAME [--slug SLUG] [--status STATUS]",
+            "required_flags": {
+                "--name": "Organization name (required)"
+            },
+            "optional_flags": {
+                "--slug": "URL-friendly identifier (optional)",
+                "--status": "Active or Inactive (default: Active)"
+            },
+            "examples": [
+                "notion agents orgs create --name 'WareflowX'",
+                "notion agents orgs create --name 'WareflowX' --slug 'wareflowx' --status 'Active'"
+            ]
+        },
+        "info": {
+            "purpose": "Get organization details",
+            "usage": "notion agents orgs info --org ORG_NAME_OR_SLUG",
+            "output": "Returns organization details with projects count"
+        }
+    }
+)
+
+# 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."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all projects (optionally filtered by organization)",
+            "usage": "notion agents projects list [--org ORG_NAME]",
+            "output": "Returns list of projects with their organizations"
+        },
+        "create": {
+            "purpose": "Create a new project in an organization",
+            "usage": "notion agents projects create --org ORG_NAME --name NAME",
+            "required_flags": {
+                "--org": "Organization name or slug (required)",
+                "--name": "Project name (required)"
+            },
+            "examples": [
+                "notion agents projects create --org 'WareflowX' --name 'Website Redesign'"
+            ]
+        },
+        "info": {
+            "purpose": "Get project details",
+            "usage": "notion agents projects info --project PROJECT_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."
+    ),
+    subcommands={
+        "list": {
+            "purpose": "List all versions (optionally filtered by project)",
+            "usage": "notion agents versions list [--project PROJECT_NAME]",
+            "output": "Returns list of versions with their projects"
+        },
+        "create": {
+            "purpose": "Create a new version in a project",
+            "usage": "notion agents versions create --project PROJECT_NAME --name VERSION",
+            "required_flags": {
+                "--project": "Project name (required)",
+                "--name": "Version name e.g. v1.0.0 (required)"
+            },
+            "examples": [
+                "notion agents versions create --project 'Website Redesign' --name 'v1.0.0'",
+                "notion agents versions create --project 'Website Redesign' --name 'sprint-1'"
+            ]
+        }
+    }
+)
+
+# 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. "
+        "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 VERSION] [--status STATUS]",
+            "output": "Returns list of tasks with their versions and status"
+        },
+        "create": {
+            "purpose": "Create a new task in a version",
+            "usage": "notion agents tasks create --version VERSION_NAME --name TASK_NAME",
+            "required_flags": {
+                "--version": "Version name (required)",
+                "--name": "Task name (required)"
+            },
+            "optional_flags": {
+                "--status": "Todo, In Progress, Done (default: Todo)",
+                "--priority": "Low, Medium, High, Critical (default: Medium)"
+            },
+            "examples": [
+                "notion agents tasks create --version 'v1.0.0' --name 'Fix login bug'",
+                "notion agents tasks create --version 'v1.0.0' --name 'Add feature' --status 'Todo' --priority 'High'"
+            ]
+        },
+        "next": {
+            "purpose": "Find next available task to work on",
+            "usage": "notion agents tasks next [--version VERSION]",
+            "description": "Finds tasks with status 'Todo' and no incomplete dependencies"
+        }
+    }
+)
+
 # =============================================================================
 # 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 +776,38 @@ 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",
+        "Create organization before creating projects",
+        "Create project before creating versions",
+        "Create version before creating tasks",
+        "Tasks must have a Version relation (required)",
+        "Projects must have an Organization relation (required)",
+        "Use 'agents tasks next' to find next available task",
     ],
     examples={
         "initial_setup": """# First time setup
@@ -357,13 +822,39 @@ 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
+
+# 1. Create organization
+notion agents orgs create --name "WareflowX" --slug "wareflowx"
+
+# 2. Create project in organization
+notion agents projects create --org "WareflowX" --name "Website Redesign"
+
+# 3. Create version in project
+notion agents versions create --project "Website Redesign" --name "v1.0.0"
+
+# 4. Create task in version
+notion agents tasks create --version "v1.0.0" --name "Fix login bug" --priority "High".""",
+
+        "query_and_create": """# List existing organizations
+notion agents orgs list
+
+# List projects in organization
+notion agents projects list --org "WareflowX"
+
+# List tasks in version
+notion agents tasks list --version "v1.0.0"
+
+# Find next task to work on
+notion agents tasks next --version "v1.0.0\"""",
+
+        "create_task": """# Create task using agents command (recommended)
+notion agents tasks create --version "v1.0.0" --name "Fix login bug"
 
-        "create_task": """# After workspace is initialized
+# Alternative: Create task directly with pages command
 notion pages create \\
   --parent TASKS_DB_ID \\
   --title "Fix login bug" \\
-  --properties '{"Status": "Todo", "Version": "VERSION_ID"}'""",
+  --properties '{"Status": "Todo", "Version": "VERSION_ID", "Priority": "High"}'""",
     },
 )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 1.6.0
+Version: 1.7.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.7.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=1efMpTrGGuUbulrk7IO5iDIw93CZjv_YkpVPcXIHheI,32267
 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.7.0.dist-info/METADATA,sha256=u205QxZNPO8eTf7S29XGFFx9QPSnYyCp5m4Cy7okHnk,11096
+better_notion-1.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+better_notion-1.7.0.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
+better_notion-1.7.0.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
+better_notion-1.7.0.dist-info/RECORD,,