bf-caprt-dev

bf-caprt-dev

Positioning

This skill is used to guide coding agents to implement business capabilities through capability-runtime rather than bypassing it to directly assemble upstream frameworks.

Default mental model:

skill / agent / workflow -> Runtime public surface -> NodeReport / host summary / service surfaces

Self-contained constraint

This skill is a self-contained skill:

• Only references within the current skill directory are allowed references/ and evals/
• It is not allowed to write docs/、examples/、tests/、help/、README.md and other external repository paths as skill dependencies
• If new facts about capability-runtime need to be added, first copy or organize them into this skill directory, then reference them in the skill body

Opening actions

1. First confirm whether the current Python environment can already import capability_runtime。
2. If it cannot be imported yet, prefer installing from PyPI; only for local source development or monorepo scenarios should you switch to editable install.
3. Use only for temporary verification PYTHONPATH as a fallback; do not treat it as a long-term delivery solution.
4. After it can be imported, continue to look at references/triad-and-routing.md and references/api-reference.md, do not write business code while guessing about the environment.

Local environment preparation

If it is local source development, then record the local repository directory as CAPRT_REPO_ROOT：

export CAPRT_REPO_ROOT=/abs/path/to/capability-runtime

First do an import precheck:

python3 -c "import capability_runtime; print('capability_runtime import ok')"

If the import fails, prefer installing from PyPI:

pip install capability-runtime

If you are modifying local source, or the repository is a monorepo / needs to follow unpublished changes, then forcontains pyproject.toml local source directorydo an editable install:

pip install -e "$CAPRT_REPO_ROOT"

If the repository is a monorepo,pyproject.toml is not in the root directory, then change the above path to the actual Python package directory.

Only for temporary verification, use PYTHONPATH as a fallback:

export PYTHONPATH="$CAPRT_REPO_ROOT${PYTHONPATH:+:$PYTHONPATH}"
python3 -c "import capability_runtime; print('capability_runtime import ok')"

Before continuing, complete at least one smoke check:

python3 -c "from capability_runtime import Runtime, RuntimeConfig; print('caprt api ok')"

When to use

When the task goal matches any of the following situations, prefer using this skill:

• Use capability-runtime to create new business capability, agent, workflow, service interfaces, or offline regression samples
• Converge existing business skills, Agent shells, and Workflow orchestration uniformly onto the Runtime public surface
• Need Runtime.run() / run_stream() / run_structured() / run_structured_stream()
• Need NodeReport, descriptor, host summary as the source of truth for program judgment or auditing
• Need RuntimeServiceFacade / RuntimeSession to implement service/session continuity
• Need invoke_capability、approval/waiting-human、resume、legacy host convergence

Do not use

The following situations should not trigger this skill:

• Ordinary general coding, unrelated to capability-runtime
• Only changing prompts, not concerned with Runtime, tests, registration, NodeReport, or the execution chain
• Want to directly learn upstream native framework APIs, such as the native way of writing Agently/TriggerFlow
• Explicitly require bypassing capability-runtime and directly connecting the provider SDK or upstream framework into the main business process
• Explicitly require “directly use skills-runtime-sdk / Agently / provider SDK to complete the business”, and do not need AgentSpec / WorkflowSpec / Runtime

Exit rules

If the user has explicitly rejected capability-runtime entry, this skill must exit, rather than following along and giving the shortest upstream path.

Typical signals:

• “No capability-runtime, only upstream”
• "Use skills-runtime-sdk directly to run the business"
• "Use Agently / TriggerFlow native writing directly, do not use Runtime"
• "Connect directly to the provider SDK, do not go through capability-runtime"

When exiting, it must converge into two sentences:

1. Boundary judgment: this does not belong to bf-caprt-dev, because the user has explicitly stated they do not want capability-runtime
2. Reassignment suggestion: only explain the more suitable skill or task category, for example:
   • bf-skillsruntime-dev
   • agently-*
   • prompt-engineering
   • General-purpose coding

Prohibited:

• Import examples for the upstream SDK
• Upstream shortest-path pseudocode
• API usage that is "guessed based on memory"
• Any implementation steps that continue to unfold following the user's request

First determine two things

Before writing code, first determine the two axes:

1. Task background

• Greenfield
  • New capability or new orchestration, with no heavy historical boundary baggage
• Legacy Convergence
  • The downstream already has a runtime boundary, task stream, approval API, registry façade, workflow slice, service façade, or session continuity, and the internal source of truth needs to be converged into capability-runtime

When unable to determine, first handle it as Legacy Convergence because it is more conservative.

2. Current primary focus

• Capability 建模
  • Determine the division of labor among skill / agent / workflow
• Workflow 编排
  • Organize the data flow and call order of multiple capabilities
• Structured Output
  • The focus is run_structured() / run_structured_stream()
• Host Convergence
  • descriptor、host summary、approval/resume、service/session
• Bridge 接线
  • Real model wiring and transport compatibility

Default routing order:

Capability 建模 -> 执行入口 -> 证据链 -> Host / Service Convergence -> Bridge

Do not jump to bridge right from the start.

Three red lines

1. Business code must not bypass capability-runtime

Regardless of what the internal bridge depends on, the main business flow must not directly call the underlying upstream framework to replace capability-runtime。

2. Workflow must not be written as directly orchestrating Skill nodes

What Workflow orchestrates is Agent / Workflow. skill is capability material and a capability source, not an external primitive of Workflow.

3. Legacy tasks must not arbitrarily change the outward-facing contract

If the downstream already has:

• task stream
• approval API
• workflow slice / replay / continue
• service façade / session continuity contract
• DB / Redis persistence schema
• projector / task event protocol

Unless the user explicitly authorizes it, do not change these surfaces; first converge the internal source of truth.

4. Canonicalize structured output first, then fallback

When structured output shows that "a field appears to be missing, but the original payload seems to still contain content," handle it in the following order first:

1. Perform a lossless scan of the original payload
2. Identify equivalent fields and error levels
3. First perform lossless canonicalize to restore canonical structured output
4. Then perform coverage / completeness / degraded determination
5. Only if it is still missing after canonicalize may retry, fallback, or estimated be allowed

One-sentence principle:

• As long as the real data is still in the payload, recover the real data first; do not rush to fabricate estimated values

Default business main path

Regardless of Greenfield or Legacy, follow this path by default first:

1. Read references/triad-and-routing.md
2. Read references/api-reference.md
3. Determine which of skill / agent / workflow it currently more resembles as an implementation form
4. If the Agent depends on skills, prepare the skills bundle / overlay / workspace
5. Write AgentSpec / WorkflowSpec
6. rt.register_many([...]) then first rt.validate()
7. Prefer using mock or sdk_native for offline regression
8. When structured results are needed, prefer using run_structured() / run_structured_stream()
9. When programmatic judgment is needed, prefer reading NodeReport、descriptor、host summary
10. When servitization is needed, then move to RuntimeServiceFacade / RuntimeSession
11. After the offline path is stable, only then switch to bridge

Greenfield: default landing approach

Decision rules

• First decide whether the capability material is skill
• Then decide whether the executable unit is agent
• When orchestration is needed, then upgrade to workflow
• By default, let Runtime become the sole execution entry point

Default practice

• skill
  • Accumulate as business capability assets
  • Consumed through the upstream source / overlay / mention / action system
• agent
  • Capability unit directly executable by Runtime
  • By default, prefer using AgentSpec(skills=[...]) to carry skills-first capabilities
• workflow
  • Only orchestrate Agent / Workflow
  • Do not directly depend on low-level Skill nodes or private bridge helpers

Minimal skeleton

from capability_runtime import AgentSpec, CapabilityKind, CapabilitySpec

agent = AgentSpec(
    base=CapabilitySpec(
        id="incident.triage",
        kind=CapabilityKind.AGENT,
        name="Incident Triage",
        description="分析输入事件并给出处置建议。",
    ),
    skills=["incident-triager"],
)

from capability_runtime import (
    WorkflowSpec,
    CapabilityKind,
    CapabilityRef,
    CapabilitySpec,
    InputMapping,
    Step,
)

workflow = WorkflowSpec(
    base=CapabilitySpec(
        id="incident.flow",
        kind=CapabilityKind.WORKFLOW,
        name="Incident Flow",
    ),
    steps=[
        Step(
            id="triage",
            capability=CapabilityRef(id="incident.triage"),
            input_mappings=[InputMapping(source="context.alert", target_field="alert")],
        ),
    ],
)

rt.register_many([agent, workflow])
assert rt.validate() == []
result = await rt.run("incident.flow", input={"alert": {...}})
assert result.node_report is not None

Legacy Convergence: conservative convergence approach

First identify whether the downstream already has these layers:

• manifest source / registry façade
• runtime boundary / executor / adapter
• projector / task stream
• approval API / HITL store
• workflow slice / continue / replay
• service façade / session continuity
• Persistent fact model

The default goal is not to rewrite them, but to determine:

• Which ones can already switch to the Runtime public surface
• Which ones should still remain at the downstream boundary
• Which outward-facing contracts cannot be changed

Recommended convergence order

Phase 1: registry / manifest / descriptor

Prefer considering:

• Runtime.register()
• Runtime.register_many()
• Runtime.register_with_manifest()
• Runtime.validate()
• Runtime.describe_capability()
• Runtime.list_capabilities()

Phase 2: host protocol internal truth

Prefer considering:

• Runtime.summarize_host_run()
• Runtime.build_approval_ticket()
• Runtime.build_resume_intent()

Phase 3: service/session boundary

Only when the task explicitly requires servitization or continuity, consider:

• RuntimeServiceFacade
• RuntimeSession

By default, do not automatically enter

The following content does not enter the first reaction by default:

• workflow slice / replay / continue rewrite
• full replacement of the service façade
• session continuity protocol rewrite
• Redis / DB fact model rework

If the task really needs these, then confirm whether the user explicitly authorizes expanding the battlefield.

Public Surface usage priority

The default business path should preferentially use

• Runtime.register() / register_many() / validate()
• Runtime.run() / run_stream()
• Runtime.run_structured() / run_structured_stream()
• Runtime.describe_capability() / list_capabilities()
• Runtime.summarize_host_run()

Host / Service scenarios should additionally consider

• Runtime.register_with_manifest()
• Runtime.build_approval_ticket()
• Runtime.build_resume_intent()
• RuntimeServiceFacade
• RuntimeSession
• make_invoke_capability_tool()

Do not depend by default on

• deep path import
• private helper
• internal adapter / engine details

Business code should import public APIs only from the package root. For details, read:

• references/api-reference.md

Runtime mode selection

Mode	Purpose	Recommendation
mock	Pure protocol / registration / orchestration logic tests	Fastest way to verify Runtime semantics
sdk_native	Default development mode	Prefer for business development
bridge	Real model / real transport wiring	Only switch after the offline path is stable

Default order:

mock -> sdk_native -> bridge

Complex task routing

When a task has exceeded the complexity of "single Agent + single run", route as follows:

• skills-first structured Agent: read references/patterns-cookbook.md "Mode 1" in
• Workflow orchestrating multiple Agents: read references/patterns-cookbook.md "Mode 2" in
• Sub-capability delegation / sub-Agent: read references/patterns-cookbook.md "Mode 3" in
• waiting-human / approval / resume: read references/patterns-cookbook.md "Mode 4" in
• service façade / session continuity: read references/patterns-cookbook.md "Mode 5" in
• Complex task coverage matrix and acceptance: read references/complex-task-matrix.md

Minimal verification checklist

Greenfield

• register_many() succeeds
• validate() is empty
• run() / run_stream() final state matches expectations
• When structured results are needed, prefer going through run_structured() / run_structured_stream()
• NodeReport exists, and key judgments do not depend on free text

Legacy Convergence

• Whether the descriptor source of truth has been switched to the Runtime public surface
• Whether the host summary can now uniformly determine success / failed / waiting-human
• Whether the internal source of truth for approval / resume is unified
• service/session only enters when needed
• Whether the outward-facing contract remains unchanged

Do / Don't

Do

• Prefer translating business problems into skill / agent / workflow
• By default, make the Agent skills-first, but maintain a balance among the three capabilities
• Add tests first, then change the registration surface, execution surface, or host source of truth
• Use NodeReport, descriptor, and host summary for programmatic judgment
• For complex tasks, prefer the local references bundled with this skill

Don't

• Do not directly use the underlying upstream framework to write the main business process
• Do not write the Workflow as directly orchestrating Skill nodes
• Do not mistake the host extension surface for the default path of ordinary business tasks
• Do not use regex on free text to determine business success or failure
• Do not conveniently rewrite the task stream, approval API, or workflow slice in a Legacy task
• Do not reference "fact documents" outside the skill directory

By default, read first

• references/triad-and-routing.md
• references/api-reference.md
• references/patterns-cookbook.md
• references/complex-task-matrix.md
• references/trigger-review-checklist.md
• evals/evals.json

One-sentence reminder

Reading upstream capabilities is for determining capability-runtime where it has already been bridged, and how the downstream boundary can be made thinner; it is not for bypassing capability-runtime to directly use upstream to implement the business.