Meta-activation layer for AI agents. Ensures AI has full context + clear goal + conditions before executing any task. Philosophy-first framework for Claude Code and any agentic AI system.
Version: 1.0.0 · License: MIT · Status: Alpha, battle-tested through one development cycle
"If AI is given full context — purpose, environment, conditions, history, principles, requirements — AI will self-execute inside its blackbox and reach the goal with absolute quality. PTAP's job is to guarantee that 'full context'."
Modern LLMs are capable. What they lack is not intelligence — it's the right conditions at the right moment. PTAP is not a framework that wraps AI with code. It is a knowledge layer + interaction discipline that supplies AI with everything it needs, on-demand, adapted to each task.
-
Knowledge > Code — When LLMs are strong, encode knowledge into content (skills, principles, traps), not rule-based code. Content is adaptive; code is rigid.
-
Interaction Abundance > Scarcity — AI has a default bias toward not bothering the user. In serious work, this bias produces silent errors. PTAP counters it: when a user explicitly allows interaction, ask more, surface more, filter less.
-
Metacognition as Core Discipline — AI must think about its own thinking. Self-doubt, confidence calibration, bias detection, output verification. Not a feature — a requirement.
When you invoke PTAP before a task, it walks the AI through:
- Classifies the task semantically (LLM-native, not rule-based)
- Retrieves relevant experience, traps, past cases, applicable tools
- Surfaces unknown unknowns and clarifying questions proactively
- Defines a quality contract (what "done" means)
- Forces methodology decisions before execution
- Plans verification gates (including adversarial subagent audits)
- Runs a V1-V7 metacognitive sweep before claiming completion
- Adapts depth to task complexity (skip for trivial, max rigor for crisis)
- Logs invocations to feed a continuous learning flywheel
All of this happens through adaptive interaction with the user — not as rigid ritual, but as a thoughtful companion that asks the right questions at the right time.
- Teams and individuals using Claude Code, Anthropic's Agent SDK, or any agentic AI platform
- Data analytics / engineering teams delivering dashboards, reports, pipelines to clients
- Product / project teams managing complex deliverables with quality requirements
- Consultancies where quality of AI-assisted work is client-visible
- Researchers studying AI governance and human-AI collaboration patterns
- Anyone who has felt: "AI is powerful, but I keep having to remind it of things I've already told it"
When you work with AI agents over time, three gaps emerge:
- Retrieval Gap — The AI knows a relevant rule/trap/case exists, but fails to recall it at the right moment.
- Usage Gap — The AI uses an existing tool/asset once when the design calls for three invocations.
- Unknown Unknowns — The AI proceeds confidently into territory it doesn't know it doesn't understand.
The symptoms are familiar:
- You catch the same errors in different projects
- You find yourself writing the same reminders before every complex task
- AI claims PASS, you find errors, you claim PASS again, errors persist
- Simple fixes that should take minutes spiral into multi-round rework
PTAP was born from watching these patterns repeat and deciding they are systemic, not accidental. Systemic problems need systemic solutions, and PTAP is one.
ptap-universal/
├── README.md You are here
├── CHARTER.md Full philosophy + 12 principles
├── LICENSE MIT
├── CHANGELOG.md Version history
│
├── skills/
│ └── ptap/
│ └── SKILL.md The full universe, LLM-native
│
├── commands/
│ ├── ptap.md Slash command: /ptap <task>
│ └── ptap-review.md Slash command: /ptap-review
│
├── tools/
│ ├── ptap_log_helper.py CLI to log invocations + feedback
│ ├── ptap_flywheel_analyzer.py Analyze logs, generate proposals
│ └── __init__.py
│
├── templates/
│ ├── trap_index_template.yaml Customize your domain traps
│ ├── task_taxonomy_template.yaml Customize your task types
│ └── project_context_template.yaml Per-project context
│
├── docs/
│ ├── GETTING_STARTED.md 15-minute setup
│ ├── PHILOSOPHY.md Deep dive on the three insights
│ ├── ARCHITECTURE.md How 7 layers interact
│ ├── FLYWHEEL.md Continuous learning design
│ └── VOCABULARY.md Named patterns (Source Trust Fallacy, etc.)
│
└── examples/
├── example_trap_library.yaml Sample customized trap index
└── example_briefing_output.md What you should expect to see
Clone into your project's .claude/ directory:
git clone https://github.com/thantrunghieu2002-cell/ptap-universal .ptap-universal
# Link into Claude Code structure
cp -r .ptap-universal/skills/ptap .claude/skills/
cp .ptap-universal/commands/ptap.md .claude/commands/
cp .ptap-universal/commands/ptap-review.md .claude/commands/
cp -r .ptap-universal/tools _shared/tools/ptapCopy templates into your workspace and fill them with your specifics:
cp .ptap-universal/templates/trap_index_template.yaml \
_shared/tools/ptap/ptap_registry/trap_index.yaml
cp .ptap-universal/templates/task_taxonomy_template.yaml \
_shared/tools/ptap/ptap_registry/task_taxonomy.yamlEdit these YAMLs to reflect your projects, your traps, your task types. See examples/ for guidance.
Method A — Slash command (most explicit):
/ptap <your task description>
Method B — Skill invocation (agent-assisted): Say in chat: "Use ptap skill for: " — or simply include "ptap" / "làm kỹ" / "strict mode" in your message.
Method C — Direct Python (programmatic):
from ptap import run_ptap
result = run_ptap("build dashboard for client X")
print(result.briefing_markdown)After a week of usage:
/ptap-review --since 7d
This produces a report of classification accuracy, trap hit rates, and auto-proposes updates to your skill content. Approve the good ones; reject the rest. Over months, your PTAP becomes sharper for your domain.
PTAP is intentionally accessible through three redundant paths:
| Path | Invocation | Use when |
|---|---|---|
| Slash | /ptap <task> |
Explicit, documented, first-class in /help |
| Skill | Agent auto-invokes on keywords | Mid-task recalibration, chaining with other skills |
| Keyword | Type "ptap" / "làm kỹ" in message | Inline, fast, natural |
This is not over-engineering. Different contexts call for different invocation styles. You never lose access because one path failed.
PTAP is not the first AI governance framework. Metacognition has been studied since Flavell (1979). Flywheel patterns have Amazon and Toyota precedents. User-gated approvals are enterprise standard.
What PTAP contributes:
- Synthesis — integrating these into one coherent framework tailored for agentic AI (Claude Code era)
- Vocabulary — naming specific AI failure patterns that lacked standard terminology: Source Trust Fallacy, Confidence Residue, Retrieval Gap, Usage Gap, Don't Bother User Bias, Verification Theater
- Adaptive Depth — briefing scales to task complexity, not one-size-fits-all
- User-gated authority — deliberate philosophical stance against autonomous auto-apply
- LLM-native skill — content over code, future-proofed as AI evolves
- Semi-auto flywheel — balance between autonomous efficiency and human editorial control
These are available to any team adopting the framework.
PTAP ships with generic templates, not our specific traps. Your workspace context is yours; what this package provides is the skeleton + philosophy + mechanisms you customize for your domain.
If your team builds dashboards, your trap library will look different from a team building biomedical models, which will look different from a team writing legal documents. The framework adapts; the content is yours.
- Not 100% always better than not using. Classifier is LLM-native, which is accurate but not perfect. Edge cases exist.
- Requires discipline to run
/ptap-reviewweekly or the flywheel doesn't turn. - Not a replacement for domain expertise. Surfaces questions the expert must answer.
- Young framework — alpha status. Expect rough edges. Contribute improvements.
- Token cost — each skill invocation loads ~5-8K tokens of content. For trivial tasks, this is overhead.
The mitigations are documented in docs/. Read them before expecting magic.
This is open-source. Contributions welcome:
- New trap discoveries — send PRs to expand the universal trap library
- Vocabulary additions — if you name a pattern worth including, propose it
- Domain templates — share your customized trap library as an example
- Case studies — document how PTAP helped (or failed) in real projects
- Bug reports / issues — file on GitHub
See CONTRIBUTING.md for guidelines.
- v1.0 (current) — alpha release with core framework
- v1.1 — refined classifier heuristics based on community feedback
- v1.2 — expanded universal trap library from contributions
- v2.0 — Level 3 flywheel (toward more automatic learning)
- Future — ports to non-Claude-Code platforms (GPT Assistants API, custom agent frameworks)
PTAP was synthesized from:
- Work in Vietnamese enterprise analytics (treasury, auto dealer, F&B domains)
- Academic research on metacognition (Flavell, Nelson-Narens)
- Industry governance frameworks (enterprise compliance, Amazon flywheel)
- Anthropic's Claude Code skill architecture
- Lessons from real failures — especially the infamous V7 three-round PASS-theater incident
It is imperfect, alpha, and shipped because waiting for perfect is the enemy of shipping useful.
MIT — see LICENSE.
Use, modify, contribute. If PTAP helps your team, a star on GitHub and a case study contribution would be appreciated but are not required.
"Full context → AI self-executes. PTAP guarantees the 'full context'."