Power Design Patterns

The main power shapes in Downcity and when to choose actions, hooks, lifecycle runtime, system text, or HTTP

Not every power should look the same.

In current Downcity, a healthy power design usually starts by choosing one primary shape.

1. Action-first power

Use this shape when the main goal is:

  • explicit user-triggered capability
  • clear command or API entry points
  • bounded one-shot work

Typical examples:

  • skill
  • sound

2. Hook or resolve power

Use this shape when the power should participate in an existing runtime chain.

Typical examples:

  • the built-in authorization capability in messenger
  • automatic ASR in sound
  • role resolver style powers

3. System-text power

Use this shape when the power's main job is to add stable runtime guidance.

Typical examples:

  • skill
  • web
  • memory

4. Lifecycle-owned runtime power

Use this shape when the power must own long-lived runtime state.

Typical examples:

  • messenger
  • task
  • shell

ActionSchedule is intentionally not modeled as a power; it is a shared Agent action module.

This is the right choice when the capability must:

  • start
  • stop
  • recover
  • keep in-memory state
  • poll or react over time

5. Runtime HTTP power

Use this shape when the power mainly exposes runtime status or control surfaces through HTTP.

This shape is suitable when a custom Power contributes dedicated status endpoints while reusing host authentication and lifecycle.

One practical rule

Do not start from “where can I quickly place this code”.

Start from:

  • is this an explicit command
  • is this chain participation
  • is this stable system guidance
  • is this lifecycle-owned runtime state
  • is this HTTP exposure