system-lifecycle-designer
Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- system-lifecycle-designer
- tags
- [ "lifecycle", "lifecycle_designer", "system-design", "state-machine", "architecture", "universal-workflow", "reconciliation", "resource-leasing", "atomic-persistence", "closed-loop" ]
- author
- Human Skills Team
- version
- 2.0.0
- description
- Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.
- trigger_patterns
- [ "lifecycle designer", "lifecycle design", "system-lifecycle-designer", "workflow design", "state machine design", "subatomic lifecycle", "atomic workflow", "reconciliation engine", "resource leasing", "daemon supervisor design", "batch job lifecycle" ]
03 SKILL.md 正文
Universal Feature Lifecycle & Workflow Design Methodology
"A software feature is not merely a function that executes; it is a state machine governing resources, identity, and invariants across time. True robustness begins at the sub-atomic lifecycle layer."
1. Scope & Primary Directive
This skill does NOT design an entire generic application or high-level product MVP.
Instead, it provides the universal, domain-agnostic methodology to design the complete, end-to-end atomic and sub-atomic lifecycle for any specific, isolated functionality integration (e.g., daemon supervisor, worker pool, batch job pipeline, database transaction context, autonomous connection pool, cache manager, or rate-limited service client).
Whenever an AI agent or software engineer is tasked with architecting, documenting, or reviewing a single functionality workflow, they must apply the 7 Invariant Pillars and select the appropriate Domain Archetype Profile defined here.
2. Leverage the human-skills Gateway
Before designing or implementing, consult specialized capabilities within the human-skills ecosystem:
| Skill / Tool | Namespace | Purpose in Lifecycle Design |
|---|---|---|
human-skills |
Gateway | Master dispatcher to inspect available capabilities before assuming or improvising. |
writing-plans |
obra_superpowers |
Structuring execution plans with exact file paths, test-driven steps, and zero placeholders. |
test-driven-development |
obra_superpowers |
Formulating failing state transition and boundary tests prior to implementation. |
linter |
my_skills |
AST-based architectural auditor to ensure unidirectional imports, sandboxing, and zero forbidden patterns. |
mermaid_view |
my_skills |
Validating and rendering workflow and state-machine Mermaid diagrams. |
# Verify skills or inspect tools
human-skills --skill_info writing-plans
human-skills --tool_info linter
3. The 7 Universal Invariant Pillars
Every functionality integration must explicitly answer and architect these 7 dimensions, regardless of domain:
flowchart TD
P1["1. Canonical Identity\n(Deterministic Content Hashing)"] --> P2["2. Pre-Commit Boundary Defense\n(Staging Sandbox & Invariant Audit)"]
P2 --> P3["3. Differential State Reconciliation\n(Candidate vs Active State Diff)"]
P3 --> P4["4. Resource Leasing & Capacity Bounds\n(Sticky Allocation & Autonomous Pooling)"]
P4 --> P5["5. Archetype State Machine\n(Complete Lifecycle Transitions)"]
P5 --> P6["6. Transactional Persistence\n(Atomic Commit & Split-Brain Defense)"]
P6 --> P7["7. Closed-Loop Bidirectional Feedback\n(Consumer to Orchestrator Signals)"]
Pillar 1: Canonical Identity & Deterministic Fingerprinting
- The Anti-Pattern: Using arbitrary runtime auto-increment IDs, random UUIDs, or unstable mutable labels to identify managed entities.
- The Universal Standard: Compute a deterministic SHA-256 fingerprint from the entity's immutable, normalized payload or configuration parameters: $$\text{Fingerprint} = \text{SHA256}(\text{CanonicalJSON}(\text{NormalizedImmutableAttributes}))$$
- Guarantee:
- Guarantees strict idempotency across restarts and repeated ingestion cycles.
- Eliminates duplicate entities masquerading under different aliases, labels, or routing handles.
Pillar 2: Pre-Commit Boundary Defense & Staging Sandbox
- The Anti-Pattern: Blindly writing raw input or newly spawned configurations directly into live production stores, runtime memory pools, or active pipelines.
- The Universal Standard: Validate the candidate entity completely before it touches live operational state:
- Schema & Invariant Check: Strict Pydantic/type validation with zero-fallback Tony Hoare boundary defense.
- Dry-Run / Syntax Audit: If the entity produces executable configs, scripts, or external specs, invoke an offline dry-run validation pass against an isolated
.tmpbuffer. - Resource Pre-Check: Verify resource availability (memory, ports, worker quota, disk space) before committing state.
- Guarantee: Invalid or corrupt configurations fail fast in isolation; active production execution is never halted by unverified inputs.
Pillar 3: Differential State Reconciliation
- The Anti-Pattern: Destructive full overwrites on every sync cycle (tearing down the entire active pool and rebuilding from scratch), or concurrent reconciliation passes causing split-brain states.
- The Universal Standard: Compute set-theoretic differential state between Candidate Ingestion ($C$) and Active State ($A$):
- Concurrency Guard: Enforce a non-reentrant state lock or optimistic concurrency control via monotonic version tags (
generation_id += 1). - Unchanged ($C \cap A$): Retain entity and existing operational leases without interruption or connection drop.
- Added ($C \setminus A$): Allocate required resource leases, stage in sandbox, and promote to active.
- Modified ($C \cap A$ with mutated payload): Perform in-place hot-patch if supported; otherwise, execute a seamless blue-green rollover.
- Missing ($A \setminus C$): Never terminate abruptly! Gracefully drain in-flight operations before releasing resources.
- Concurrency Guard: Enforce a non-reentrant state lock or optimistic concurrency control via monotonic version tags (
Pillar 4: Resource Leasing, Quotas & Autonomous Pooling
- The Anti-Pattern: Unbounded allocation, volatile index-based slot assignment (
index + base), or synchronous on-demand fetching inside hot caller loops causing latency spikes. - The Universal Standard:
- Explicit Resource Leases: Any scarce or shared resource (ports, GPU memory, worker threads, DB connections, rate tokens) must be managed through an explicit
LeaseManagerthat issues unique, tracked lease tokens. - Autonomous Pre-Warming (High-Latency Dependencies):
When upstream dependency provisioning introduces high latency (>1-2s), synchronous on-demand allocation inside user requests is strictly forbidden.
- Maintain an autonomous background worker maintaining target warm capacity: $$N_{\text{target}} = \text{Peak Concurrency} \times \text{Safety Factor}$$
- When available warm items drop below replenishment threshold ($T_{\text{replenish}}$), asynchronously replenish without blocking active consumers.
- TTL & Expiration Defense: Prune stale entities according to proactive expiration buffers ($t_{\text{expiry}} - \Delta t_{\text{safety}}$).
- Explicit Resource Leases: Any scarce or shared resource (ports, GPU memory, worker threads, DB connections, rate tokens) must be managed through an explicit
Pillar 5: Archetype State Machine Topologies
Do not force a single monolithic state machine onto every project. Select the appropriate Archetype Profile based on the entity's operational lifecycle:
flowchart TD
Entity["Entity Assessment"] --> Decision{"What is the entity's operational nature?"}
Decision -->|"Long-Running Daemon / Process Pool"| ArchA["Archetype A: Managed Supervisor Pool"]
Decision -->|"Discrete Batch Job / Task"| ArchB["Archetype B: Finite Batch Pipeline"]
Decision -->|"Scoped Request / Transaction"| ArchC["Archetype C: Request/Transaction Context"]
Decision -->|"Recyclable Resource / Connection"| ArchD["Archetype D: Resource Pool Entity"]
Archetype A: Managed Supervisor Pool (Long-running Services & Daemons)
Designed for managed processes, proxy daemons, background workers, and persistent connections:
stateDiagram-v2
[*] --> Ingested
Ingested --> Staged: Fingerprint & Validate
Staged --> Active: Bound & Healthy
Active --> Degraded: Health Check Warning
Degraded --> Active: Health Restored
Degraded --> Quarantined: Threshold Breached
Active --> Draining: Upstream Deregistration
Quarantined --> Draining: Quarantine Timeout
state Draining {
[*] --> RejectNew
RejectNew --> WaitInFlight
WaitInFlight --> DrainComplete
}
Draining --> Tombstone: In-flight == 0 / Deadline Reached
Tombstone --> Purged: Tombstone TTL Expired
Purged --> [*]: Lease Recycled
Archetype B: Finite Batch Pipeline (Jobs, Tasks & Transformations)
Designed for discrete work units, ETL tasks, video transcode jobs, and async commands:
stateDiagram-v2
[*] --> Submitted: Enqueued
Submitted --> Validated: Payload & Quota Checked
Validated --> Queued: Awaiting Worker Slot
Queued --> Running: Worker Acquired
Running --> Completed: Execution Success
Running --> Failed: Unrecoverable Error
Running --> Cancelled: Explicit Abort
Failed --> Retrying: Retry Policy Eligible
Retrying --> Queued: Exponential Backoff
Completed --> Archived: Retained Output Stored
Failed --> Archived: Error Log Stored
Cancelled --> Archived: Partial Cleanup
Archived --> [*]
Archetype C: Request / Transaction Context (APIs & Atomic Mutations)
Designed for HTTP requests, RPC calls, database units-of-work, and interactive operations:
stateDiagram-v2
[*] --> Received: Input Arrival
Received --> Authenticated: Identity Verified
Authenticated --> Validated: Schema & Invariants Passed
Validated --> Processing: Unit of Work Active
Processing --> Committed: Invariant Success
Processing --> RolledBack: Invariant or System Error
Committed --> Responded: Success Payload Sent
RolledBack --> Responded: Error Payload Sent
Responded --> [*]: Scope Terminated
Archetype D: Resource Pool Entity (Connections, Buffers, Tokens)
Designed for database connection pools, memory buffers, pre-warmed sessions, and tokens:
stateDiagram-v2
[*] --> Initializing: Allocation
Initializing --> Available: Health Verified
Available --> Leased: Checked Out by Caller
Leased --> InUse: Work Underway
InUse --> Returning: Work Finished
Returning --> Available: Sanitized & Healthy
Returning --> Evicted: Unhealthy / Stale
Available --> Evicted: Idle TTL Expired
Evicted --> Destroyed: Resources Released
Destroyed --> [*]
Pillar 6: Transactional Persistence & Split-Brain Defense
- The Anti-Pattern: Sequential writes across multiple independent files. If the process crashes or disk fills after writing File A but before writing File B, the system enters an unrecoverable split-brain state.
- The Universal Standard:
- Single-File Updates: Write to isolated temporary buffer (
.tmp), flush and sync (os.fsync), then execute an atomic file swap (os.replace). - Multi-File Updates:
- Directory Pointer Swap: Write all related files into a timestamped/versioned directory (e.g.,
data/versions/v42/), fsync, and update a singlecurrentsymlink/pointer atomically. - Write-Ahead Log (WAL) / Transaction Manifest: Write an immutable transaction manifest declaring the commit intent. Only after manifest commit are changes applied. On restart, any half-written state is rolled back cleanly.
- Directory Pointer Swap: Write all related files into a timestamped/versioned directory (e.g.,
- Crash Recovery: On restart, always clean dangling
.tmpbuffers and resume strictly from the last verified snapshot.
- Single-File Updates: Write to isolated temporary buffer (
Pillar 7: Closed-Loop Bidirectional Feedback Contract
- The Anti-Pattern: One-way fire-and-forget architectures. The orchestrator produces configuration; consumers read it passively. When a consumer discovers an anomaly or failure, it has no channel to alert the orchestrator without triggering a costly full system restart.
- The Universal Standard: Establish an explicit event channel or callback interface:
- Consumer Anomaly Signal: When an active entity encounters recurring runtime failures (e.g., connection reset, consecutive timeouts, poison payload), the consumer notifies the orchestrator:
orchestrator.notify_anomaly(entity_id, reason). - Surgical Quarantine & Eviction: The orchestrator transitions only that specific entity to
DegradedorQuarantined, releases its lease, and provisions a replacement without recycling healthy peers. - Circuit Breaker: If pool-wide error rates breach thresholds, temporarily trip the circuit breaker and fall back to safe degradation mode.
- Consumer Anomaly Signal: When an active entity encounters recurring runtime failures (e.g., connection reset, consecutive timeouts, poison payload), the consumer notifies the orchestrator:
4. Canonical Workflow Document Template (docs/workflows/)
When documenting any feature lifecycle, adhere to this standard layout:
# [Component Name] Lifecycle & Workflow
## 1. Overview & Single Responsibility
[1 concise paragraph defining the boundaries: what it owns, what it isolates, and what it delegates.]
## 2. Selected Lifecycle Archetype
[State whether this is Archetype A (Daemon Pool), B (Batch Pipeline), C (Transaction Scope), or D (Resource Pool) and justify why.]
## 3. Sub-Atomic Invariant Guarantees
[Markdown Table mapping the 7 Invariant Pillars to project-specific guarantees.]
## 4. End-to-End Workflow Diagram
[Mermaid flowchart TD tracing: Trigger -> Ingestion -> Fingerprint -> Diff/Validation -> Execution -> Persistence -> Feedback.]
## 5. Lifecycle State Machine
[Mermaid stateDiagram-v2 illustrating complete states and transition guards for the chosen archetype.]
## 6. Failure Modes, Self-Healing & Invariant Checklist
[Markdown Table detailing specific failure modes, detection mechanism, and automated deterministic mitigation.]
5. Isolated Subsystem & File-by-File Implementation Sequence
-
Enforce Single-Facade Subsystem Boundaries:
- Keep internal sub-engines and private worker units strictly isolated within their domain package (e.g.,
src/<subsystem>/helpers/or private modules). - Expose only a single public manager/orchestrator facade with an explicit, typed interface (
start(),stop(),execute(),notify_anomaly()).
- Keep internal sub-engines and private worker units strictly isolated within their domain package (e.g.,
-
The 5-Step Implementation Loop (One File at a Time):
- Step 1 (Analyze): Map Current State vs. Target State, identifying edge cases, concurrency boundaries, and data contracts.
- Step 2 (Implement): Write clean, production-grade code adhering strictly to the Tony Hoare rule (no
Nonereturns, strict Pydantic schemas, typed exceptions). No docstrings or comments inside implementation code. - Step 3 (Lint): Run the architectural linter to verify zero forbidden imports, no raw
pathliboutsideconfig/, and strict single responsibility. - Step 4 (Verify & Time): Execute isolated unit tests asserting state machine transitions and boundary defenses.
- Step 5 (Orchestrate): Validate the full end-to-end integration test verifying multi-component orchestration.
6. Cross-Platform Runtime & Concurrency Checklist
When auditing or designing any lifecycle engine, verify these 5 cross-platform invariants:
- Re-Entrant Cross-Platform File & State Locking:
- Avoid platform-locked POSIX calls (
fcntl.flock) in portable code. Use cross-platform libraries (such asfilelock) or database/Redis advisory locks with explicit timeouts and context managers to prevent thread/process self-deadlock.
- Avoid platform-locked POSIX calls (
- Lock-Free External I/O & In-Memory Rollback:
- Never hold a synchronization lock during external network or high-latency filesystem I/O. Perform pre-flight I/O outside critical sections, stage mutations in memory, and acquire locks solely for atomic state swaps.
- Cross-Platform Process Supervision & PID Verification:
- Never rely on
/proc/paths or rawos.kill(pid, 0)which fail on Windows, macOS, and containers with PID recycling. Use cross-platform process management (such aspsutil) to verify process creation time, status, and executable command line before signaling.
- Never rely on
- Graceful Signal Handling Across Platforms:
- Handle termination signals (
SIGTERM,SIGINT) gracefully. For background child processes, ensure clean shutdown protocols that allow active in-flight tasks to drain before forced termination.
- Handle termination signals (
- Structured Async Supervision & Thread Boundaries:
- Long-running orchestrators must offload blocking synchronous I/O via
asyncio.to_thread. Implement cancellation tokens sostop()awaits in-flight tasks before concluding teardown.
- Long-running orchestrators must offload blocking synchronous I/O via
04 同仓库更多 Skills
style-sampling
Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.
reverse-any-video
Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.
typescript-patterns
TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.
test-collaboration
Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.
story-lifecycle
Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.
skill-host-compat
Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.