[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6WWPQ2D46MPHRBTR3AV4VKX":3,"skill-same:01M6WWPQ2D46MPHRBTR3AV4VKX":94},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":67,"commitSha":68,"skillDirectory":69,"forksCount":14,"repositoryHtmlUrl":70,"repositoryHomepageUrl":71,"ownerHtmlUrl":72,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":73,"install":74,"resources":87},"01M6WWPQ2D46MPHRBTR3AV4VKX","state-machine-management",null,"Legacy\u002Fmigration guidance for v1 StateMachine entities. In v2, lifecycle\nrules are implementation contracts owned by MCP servers, not first-class\nrecords to create during normal project work.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fstate-machine-management\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"state","state machine management","state machine","management","machine","project work","normal","for","v1","event","keep","records","MCP","project","state-machine","Legacy","log","Rules","lifecycle","create","2026-11-10 10:12:30",false,"---\nname: state-machine-management\ndescription: |\n  Legacy\u002Fmigration guidance for v1 StateMachine entities. In v2, lifecycle\n  rules are implementation contracts owned by MCP servers, not first-class\n  records to create during normal project work.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv2\n    id: SKILL-state-machine-management\n    version: \"1.0.0\"\n    created: 2026-04-06T00:00:00Z\n    category: processkit\n    layer: 3\n    uses:\n      - skill: event-log\n        purpose: Log events to keep the audit trail accurate after every write.\n    provides:\n      primitives: [StateMachine]\n      templates: [statemachine]\n---\n\n# State Machine Management\n\n## Intro\n\nIn v1, a StateMachine defined valid states and transitions for a\nprimitive. In v2, StateMachine is not a first-class primitive authoring\nsurface. Lifecycle rules live in the owning MCP server or implementation\ncontract, and transitions go through MCP tools that return structured\nerrors when a move is invalid.\n\n## Overview\n\n### Legacy v1 shape\n\n```yaml\n---\napiVersion: processkit.projectious.work\u002Fv1\nkind: StateMachine\nmetadata:\n  id: SM-workitem\n  name: workitem\n  created: 2026-04-06T00:00:00Z\nspec:\n  description: \"WorkItem lifecycle with a formal review state.\"\n  initial: backlog\n  terminal: [done, cancelled]\n  states:\n    backlog:\n      description: \"Not started.\"\n      transitions:\n        - to: in-progress\n        - to: cancelled\n    in-progress:\n      description: \"Being actively worked on.\"\n      transitions:\n        - to: review\n        - to: blocked\n        - to: cancelled\n    blocked:\n      description: \"Cannot proceed until a blocker is resolved.\"\n      transitions:\n        - to: in-progress\n        - to: cancelled\n    review:\n      description: \"Awaiting review.\"\n      transitions:\n        - to: done\n        - to: in-progress\n    done:\n      description: \"Complete.\"\n      transitions: []\n    cancelled:\n      description: \"Abandoned.\"\n      transitions: []\n---\n```\n\n### v2 lifecycle changes\n\nDo not create new StateMachine records for v2 projects. To change a\nlifecycle, update the owning MCP server or its reviewed implementation\ncontract, then migrate affected records explicitly.\n\nLifecycle changes must:\n- Keep the same `initial` state (or migrate existing data).\n- Not remove states that existing entities are currently in.\n- Add new transitions only from states that already exist.\n\n### Workflow\n\n1. Identify the MCP server that owns the entity lifecycle.\n2. Change the server contract and tests for allowed transitions.\n3. Audit existing entities for states or edges the new contract removes.\n4. Write or run a Migration for affected records.\n5. Log the state-change policy update through the normal event path.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Cycles in the state graph without explicit handling.** A cycle\n  (e.g., `in-review → in-progress → in-review`) is fine if it's\n  intentional, but every cycle should be marked and have an exit\n  criterion. Unmarked cycles cause infinite loops in process\n  execution.\n- **Terminal states with outgoing transitions.** A \"terminal\"\n  state by definition has no outgoing edges. If `cancelled` has a\n  transition to `re-opened`, then `cancelled` isn't terminal —\n  rename it. Mislabeled terminals confuse downstream queries\n  filtering by lifecycle stage.\n- **Missing initial state declaration.** Every state machine\n  needs an explicit `initial` state. Without it, new entities\n  have no lawful starting point and the validator can't reject\n  malformed creations.\n- **Creating new StateMachine records for v2 work.** That keeps the\n  legacy primitive alive and bypasses the owning MCP server contract.\n  Treat StateMachine files as migration inputs only.\n- **State machine that doesn't match the entity's actual\n  lifecycle.** If the schema says a workitem can be cancelled but\n  the state machine has no `cancelled` state, the two are out of\n  sync and queries break. Schema and state-machine must agree —\n  treat them as one unit when changing either.\n- **Forgetting to update consumers when transitions change.**\n  When you remove a transition (e.g., dropping `in-progress →\n  done` direct), every workitem currently in `in-progress` is\n  stranded. Audit current entities before removing transitions\n  and write a Migration if any are affected.\n- **Adding states without removing dead ones.** State machines\n  accumulate cruft over time. When you introduce a new state\n  that supersedes an old one, remove or deprecate the old one.\n  Otherwise the graph becomes a dictionary of every state anyone\n  ever proposed.\n- **Project-level lifecycle rules that diverge silently from\n  defaults.** If a project changes lifecycle behavior, record the\n  rationale as a DecisionRecord. Future maintainers need to know\n  why the project's flow differs from processkit's default.\n\n## Full reference\n\n### Fields\n\n| Field         | Type         | Notes                                                |\n|---------------|--------------|------------------------------------------------------|\n| `description` | string       | What this machine is for                             |\n| `initial`     | string       | Starting state for new entities                     |\n| `terminal`    | list[string] | States with no outgoing transitions                  |\n| `states`      | map          | `state_name → {description, transitions}`           |\n\n### Transition object\n\n```yaml\ntransitions:\n  - to: \u003Cstate-name>\n    guard: \"optional human-readable precondition\"\n    on_enter: \u003Cevent-type>        # LogEntry event to emit\n    required_role: \u003Crole-name>    # who is allowed to make the transition\n```\n\nGuards are advisory unless enforced by an MCP server that knows about them.\n\n### Validation\n\n- No cycles from terminal states.\n- Every non-terminal state has at least one outgoing transition.\n- Every state referenced in `transitions` must exist in `states`.\n- `initial` must exist in `states`.\n\n### Machine history\n\nLifecycle contract changes should have LogEntries rather than git commits\nalone. This lets queries reason about \"what did the valid states look like\non date X?\" without treating StateMachine as a new v2 entity.\n\n### Multiple machines for one kind\n\nLegacy v1 contexts may contain multiple machines for one primitive kind.\nDuring v2 migration, collapse those variants into explicit WorkItem types,\nArtifact-backed policy, or separate MCP lifecycle contracts rather than\ncreating new StateMachine records.\n","# State Machine Management\n\n## Intro\n\nIn v1, a StateMachine defined valid states and transitions for a\nprimitive. In v2, StateMachine is not a first-class primitive authoring\nsurface. Lifecycle rules live in the owning MCP server or implementation\ncontract, and transitions go through MCP tools that return structured\nerrors when a move is invalid.\n\n## Overview\n\n### Legacy v1 shape\n\n```yaml\n---\napiVersion: processkit.projectious.work\u002Fv1\nkind: StateMachine\nmetadata:\n  id: SM-workitem\n  name: workitem\n  created: 2026-04-06T00:00:00Z\nspec:\n  description: \"WorkItem lifecycle with a formal review state.\"\n  initial: backlog\n  terminal: [done, cancelled]\n  states:\n    backlog:\n      description: \"Not started.\"\n      transitions:\n        - to: in-progress\n        - to: cancelled\n    in-progress:\n      description: \"Being actively worked on.\"\n      transitions:\n        - to: review\n        - to: blocked\n        - to: cancelled\n    blocked:\n      description: \"Cannot proceed until a blocker is resolved.\"\n      transitions:\n        - to: in-progress\n        - to: cancelled\n    review:\n      description: \"Awaiting review.\"\n      transitions:\n        - to: done\n        - to: in-progress\n    done:\n      description: \"Complete.\"\n      transitions: []\n    cancelled:\n      description: \"Abandoned.\"\n      transitions: []\n---\n```\n\n### v2 lifecycle changes\n\nDo not create new StateMachine records for v2 projects. To change a\nlifecycle, update the owning MCP server or its reviewed implementation\ncontract, then migrate affected records explicitly.\n\nLifecycle changes must:\n- Keep the same `initial` state (or migrate existing data).\n- Not remove states that existing entities are currently in.\n- Add new transitions only from states that already exist.\n\n### Workflow\n\n1. Identify the MCP server that owns the entity lifecycle.\n2. Change the server contract and tests for allowed transitions.\n3. Audit existing entities for states or edges the new contract removes.\n4. Write or run a Migration for affected records.\n5. Log the state-change policy update through the normal event path.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Cycles in the state graph without explicit handling.** A cycle\n  (e.g., `in-review → in-progress → in-review`) is fine if it's\n  intentional, but every cycle should be marked and have an exit\n  criterion. Unmarked cycles cause infinite loops in process\n  execution.\n- **Terminal states with outgoing transitions.** A \"terminal\"\n  state by definition has no outgoing edges. If `cancelled` has a\n  transition to `re-opened`, then `cancelled` isn't terminal —\n  rename it. Mislabeled terminals confuse downstream queries\n  filtering by lifecycle stage.\n- **Missing initial state declaration.** Every state machine\n  needs an explicit `initial` state. Without it, new entities\n  have no lawful starting point and the validator can't reject\n  malformed creations.\n- **Creating new StateMachine records for v2 work.** That keeps the\n  legacy primitive alive and bypasses the owning MCP server contract.\n  Treat StateMachine files as migration inputs only.\n- **State machine that doesn't match the entity's actual\n  lifecycle.** If the schema says a workitem can be cancelled but\n  the state machine has no `cancelled` state, the two are out of\n  sync and queries break. Schema and state-machine must agree —\n  treat them as one unit when changing either.\n- **Forgetting to update consumers when transitions change.**\n  When you remove a transition (e.g., dropping `in-progress →\n  done` direct), every workitem currently in `in-progress` is\n  stranded. Audit current entities before removing transitions\n  and write a Migration if any are affected.\n- **Adding states without removing dead ones.** State machines\n  accumulate cruft over time. When you introduce a new state\n  that supersedes an old one, remove or deprecate the old one.\n  Otherwise the graph becomes a dictionary of every state anyone\n  ever proposed.\n- **Project-level lifecycle rules that diverge silently from\n  defaults.** If a project changes lifecycle behavior, record the\n  rationale as a DecisionRecord. Future maintainers need to know\n  why the project's flow differs from processkit's default.\n\n## Full reference\n\n### Fields\n\n| Field         | Type         | Notes                                                |\n|---------------|--------------|------------------------------------------------------|\n| `description` | string       | What this machine is for                             |\n| `initial`     | string       | Starting state for new entities                     |\n| `terminal`    | list[string] | States with no outgoing transitions                  |\n| `states`      | map          | `state_name → {description, transitions}`           |\n\n### Transition object\n\n```yaml\ntransitions:\n  - to: \u003Cstate-name>\n    guard: \"optional human-readable precondition\"\n    on_enter: \u003Cevent-type>        # LogEntry event to emit\n    required_role: \u003Crole-name>    # who is allowed to make the transition\n```\n\nGuards are advisory unless enforced by an MCP server that knows about them.\n\n### Validation\n\n- No cycles from terminal states.\n- Every non-terminal state has at least one outgoing transition.\n- Every state referenced in `transitions` must exist in `states`.\n- `initial` must exist in `states`.\n\n### Machine history\n\nLifecycle contract changes should have LogEntries rather than git commits\nalone. This lets queries reason about \"what did the valid states look like\non date X?\" without treating StateMachine as a new v2 entity.\n\n### Multiple machines for one kind\n\nLegacy v1 contexts may contain multiple machines for one primitive kind.\nDuring v2 migration, collapse those variants into explicit WorkItem types,\nArtifact-backed policy, or separate MCP lifecycle contracts rather than\ncreating new StateMachine records.\n",{"name":5,"metadata":49,"description":66},{"processkit":50},{"id":51,"uses":52,"layer":56,"created":57,"version":58,"category":59,"provides":60,"apiVersion":65},"SKILL-state-machine-management",[53],{"skill":54,"purpose":55},"event-log","Log events to keep the audit trail accurate after every write.",3,1775433600000,"1.0.0","processkit",{"templates":61,"primitives":63},[62],"statemachine",[64],"StateMachine","processkit.projectious.work\u002Fv2","Legacy\u002Fmigration guidance for v1 StateMachine entities. In v2, lifecycle\nrules are implementation contracts owned by MCP servers, not first-class\nrecords to create during normal project work.\n","main","4876a92620ee792aac2ac9a1a806322d8a572367","archive\u002Fprocesskit-install-20261101\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fstate-machine-management","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":75,"prompt":85,"zipAvailable":86},[76,79,82],{"tool":77,"command":78},"npx","npx skills add projectious-work\u002Fprocesskit --skill state-machine-management",{"tool":80,"command":81},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill state-machine-management",{"tool":83,"command":84},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill state-machine-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fstate-machine-management\u002FSKILL.md",true,[88],{"path":89,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":92,"sourceHtmlUrl":93},"assets\u002Fstatemachine.yaml","ASSET","资产文件",260,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fstate-machine-management\u002Fassets\u002Fstatemachine.yaml",[95,116,135,154,169,187],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":102,"publishedAt":44},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[101],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[27,103,43,104,105,106,107,108,109,110,97,111,112,113,32,114,115],"skill management","update","package","alpha","work","list","manage","ontology","get","as","manifests","skill package","transition",{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":123,"publishedAt":44},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[122],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[27,124,125,36,126,127,106,107,128,129,109,130,131,132,111,133,134],"schema","schema management","workflows","validation","generated","rebuild","contracts","wed","deterministic","contract","mode",{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":141,"publishedAt":44},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[27,142,143,43,104,144,106,107,40,145,146,147,111,148,33,149,150,151,152,153],"proposition","proposition management","index","world","record","query","creation","interface","updates","facts","claims","WSJF",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":160,"publishedAt":44},"01M6X5KMQ83QN9M6MPWZM7344F","ontology-management","Manage generated v1 ontology entities that do not require a dedicated domain server.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fontology-management\u002FSKILL.md",[],[27,110,161,43,106,42,162,128,163,40,109,164,165,111,166,34,33,167,32,168],"ontology management","archive","roadmap","do","domain","iteration","measurement","generic",{"skillNo":170,"name":171,"nameZh":6,"description":172,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":173,"categories":174,"keywords":175,"publishedAt":44},"01M6X5KCY2DN3SM21RERSFNEBT","okf-compatibility","Import, export, and validate conformant Open Knowledge Format bundles.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fokf-compatibility\u002FSKILL.md",[],[176,177,178,179,106,180,181,182,107,183,184,185,186],"okf","compatibility","okf compatibility","validate","open","knowledge","format","export","bundles","bundle","import",{"skillNo":188,"name":189,"nameZh":6,"description":190,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":191,"categories":192,"keywords":193,"publishedAt":44},"01M6X5JA8S5PNGJVFW4EQY8T83","capability-management","Manage versioned Capability entities and their governed lifecycle.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fcapability-management\u002FSKILL.md",[],[27,194,195,43,104,144,106,42,107,108,40,196,109,146,111,34,33,149,197,115],"capability","capability management","queries","changes"]