DEV Community: Fattain Naime

I Was Tired of Writing the Same Design Docs From Scratch, So I Built a Skill Library for It

Fattain Naime — Thu, 16 Jul 2026 10:20:22 +0000

Every time I started a new feature, I went through the same routine. Open a blank doc. Try to remember what sections a proper technical spec needs. Copy an old ADR template from a previous project and strip out the parts that don't apply. Realize halfway through that I forgot to think about rollback steps, or access control, or what happens when the thing fails at 3 AM.

None of this is hard work. It is just repetitive, and repetitive work is exactly the kind of thing that gets skipped when you are in a hurry. And skipping it is how you end up shipping a feature with no threat model, no rollback plan, and no one on the team quite sure why a decision was made six months later.

So I built engineering-docs. It is a set of 21 skills for coding agents that cover the full lifecycle of writing software, from the first fuzzy idea to the postmortem after something breaks in production.

The actual problem I was solving

I work across a few different projects at once, things like OwnPay, a self-hosted payment gateway, and a couple of security tools. Every one of them needs the same kind of documentation. A spec before you build. An architecture doc once the shape of the system is clear. A threat model before anything touches money or user data. A deployment plan before you push to production. A postmortem when something goes wrong, because something always eventually goes wrong.

I know how to write all of these. That was never the issue. The issue was doing it consistently, every single time, without cutting corners because I was tired or the deadline was close. And when I started leaning on AI coding agents for more of my daily work, I noticed they had the exact same problem I did. Ask an agent to "design the database for this feature" and you will usually get a handful of CREATE TABLE statements with no thought given to indexing strategy, migration rollback, or why a particular normalization choice was made. Ask it to draft an API and you get endpoints with no error contract, no versioning strategy, nothing about rate limiting.

The agent is not being lazy. It just does not know that a real system architecture document has a specific shape, or that a good threat model follows STRIDE, or that a proper API design references the Richardson Maturity Model. That knowledge lives in the head of whoever taught it, and most of the time nobody taught it anything at all. It is just pattern matching on whatever half-finished specs happen to be common in its training data.

So the fix was not "write better prompts every time." The fix was to encode the actual structure of good engineering documentation into something the agent could load and follow automatically, the same way a junior engineer eventually internalizes the format after seeing enough good examples from a senior engineer.

What is actually inside

The repo has 21 skills, and they are grouped into five phases that roughly match how a real project moves from idea to production.

Discovery and planning. This is where you start when you only have a rough idea. There is a skill for building out user personas with actual jobs-to-be-done and success metrics, not the generic "Sarah, 32, busy professional" placeholder personas that show up in every template. There is also a project plan skill for milestones, a RACI matrix, and a work breakdown structure.

Specification and feasibility. Before anyone writes code, there is a skill that produces a proper Software Requirements Specification following ISO/IEC/IEEE 29148, using EARS syntax for the actual requirements. There is also a feasibility study skill, so you can sanity check whether an idea is realistic before committing resources to it.

Architecture and product design. This is the biggest group, and it is where most of the day-to-day value shows up for me. System architecture using the C4 model. Database design with real ERDs and a proper data dictionary down to indexes and cascade rules. API design aligned to OpenAPI 3.1, with RFC 7807 error handling instead of made-up error shapes. Architecture Decision Records, written the way ADRs are supposed to be written: immutable once accepted, with alternatives and trade-offs actually spelled out instead of just the final decision.

Risk and quality. A threat model skill using STRIDE and OWASP, which is the part that catches the security gaps I would otherwise only notice during a security audit. A test strategy document. An implementation plan that orders the work by dependency instead of just listing tasks.

Deployment and operations. Deployment plans with explicit go and no-go gates, not just "deploy on Friday and hope." SLO and error budget documents. Runbooks in the format Google's SRE teams use, connecting alerts to diagnosis to escalation. A disaster recovery plan with actual RTO and RPO targets. And a blameless postmortem skill using the Five Whys method, because the point of a postmortem is to fix the system, not to find someone to blame.

There is also an orchestrator skill called using-engineering-docs that sits on top of all of this. You describe a raw idea to it, and it interviews you with a handful of targeted questions, figures out which of the 21 skills actually apply, and sequences them in the right order. You do not have to remember which skill to reach for. It figures that out from the conversation.

Why it interviews you before writing anything

This part matters more than it sounds like it should. The skills do not just generate a document the moment you ask for one. They ask three to five clarifying questions first, the same way a good senior engineer would push back on a vague ticket before writing any code.

If you ask for a database design and you have not said anything about expected read and write volume, it asks. If you ask for an API design and have not mentioned whether this needs to support mobile clients with unreliable connections, it asks. When there genuinely is a gap that cannot be resolved through a question, the doc gets an explicit marker for it instead of a made-up answer. Assumptions get flagged with 🔶 and open questions get flagged with 🔵, right in the document, so anyone reading it later knows exactly which parts were confirmed and which parts still need a decision.

I added that after noticing how often AI-generated docs read as confident and complete while actually being full of quiet, unstated assumptions. A document that pretends to have all the answers is more dangerous than one that honestly marks what it does not know yet.

Getting it running

If you want to try it, the fastest way is:

npx engineering-docs

It detects your environment and asks which agent harness you are using. Right now that covers Claude Code, Cursor and Windsurf, Kimi Code, Codex and GitHub Copilot, and Gemini through Antigravity. Each one gets its own manifest format, since Cursor expects .mdc rule files and Claude Code expects a plugin structure, but you do not need to know any of that going in.

For Claude Code specifically, you can also register it as a plugin marketplace directly:

/plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs

There are also plain shell and PowerShell scripts in the repo if you would rather skip npx entirely and see exactly what gets copied where.

One small thing I was careful about: the install process never overwrites AGENTS.md, GEMINI.md, or CLAUDE.md if you already have one. If those files exist at the destination, the installer just skips them and logs that it did. I did not want a global install command quietly wiping out someone's existing agent configuration.

Why skills instead of one giant prompt

I could have written this as one long system prompt that tries to cover every kind of document. I tried that first, actually, and it did not work well. A single prompt trying to hold the format for an ADR, a database design doc, and an incident postmortem all at once either gets too vague to be useful or so long that the agent starts ignoring parts of it.

Splitting it into 21 separate, focused skills that auto-trigger based on what you are actually asking for keeps each one sharp. The database design skill only has to be good at database design. It does not need to also know the format for a disaster recovery plan. And because they are composable, the orchestrator skill can pull in exactly the ones a given project needs instead of forcing every project through the same fixed checklist.

What I would still like to add

The skills library is not finished, and I do not think it ever really will be in the sense of being "done." Software engineering practice keeps evolving, and a couple of areas I want to build out next are more depth on data pipeline and ETL design, and a skill specifically for migration planning when you are moving off legacy infrastructure, which is a problem I run into constantly with clients still running on old shared hosting setups.

If you try it and hit a gap, or you think a skill is missing something a real senior engineer would ask about, open an issue or a PR. The contributing guide covers how the YAML frontmatter and coaching blocks are structured, so adding a new skill is mostly a matter of following the existing pattern rather than reverse engineering it from scratch.

Repository: github.com/fattain-naime/engineering-docs
License: MIT

If you have ever shipped a feature and realized three weeks later that nobody actually wrote down why a decision was made, this might save you from doing that again.

I Got Tired of Renting My Payment Infrastructure, So I Built OwnPay

Fattain Naime — Thu, 16 Jul 2026 04:34:27 +0000

If you have ever run a small business online, you know the drill. You sign up for a payment processor, hand over your customer data, watch two to three percent of every sale disappear into fees, and hope the platform does not change its terms next year.

I got tired of that setup. So over the past several months I built OwnPay, a self-hosted, open-source payment gateway platform written in PHP. This post is not a sales pitch. It is a technical walkthrough of why I built it, how it is architected, and what I learned building a system that touches money.

The problem with renting your payment stack

Most payment platforms today are SaaS. You do not own the server, you do not own the database, and you definitely do not own the customer data that flows through checkout. That is fine for a lot of businesses, but it creates three recurring pain points:

Fees compound over time. A percentage cut sounds small until your transaction volume grows.
Vendor lock-in is real. Migrating away from a processor after two years of integration work is painful.
Local payment rails are often an afterthought. If you are building for markets in South or Southeast Asia, mobile financial services like bKash, Nagad, or GCash are not always first-class citizens in Western-built platforms.

I work out of Dhaka, Bangladesh, so that last point hit close to home. Local MFS integrations are usually bolted on as an afterthought or missing entirely. I wanted something that treated them as equally important as Stripe or PayPal.

What OwnPay actually is

OwnPay is a self-hosted payment orchestrator. It is not a payment processor itself. It sits on your own server, between your storefront and whichever gateway your customer chooses, and it handles the parts that are painful to build correctly: checkout rendering, gateway routing, signature and callback verification, ledger bookkeeping, and notifications back to your store.

The flow looks like this:

A few things that make it different from a typical payment library:

Multi-brand, single install. One OwnPay installation can run multiple isolated brands (stores), each with its own custom domain, gateways, and checkout theme. Isolation happens at the database query layer through a TenantScope trait, so a single super-admin can manage several storefronts without any data bleeding between them. A DomainMiddleware resolves the incoming custom domain and routes the checkout to the right brand, while admin routes stay locked to the master domain.

White-label by default. The checkout page shows your logo, your colors, your domain. OwnPay never appears in the customer-facing experience. That was a deliberate design decision, not an add-on feature.

Gateways as plugins. Every payment gateway is a plugin living under modules/gateways/<slug>/ with a manifest.json and an adapter implementing GatewayAdapterInterface. Out of the box there are 123 built-in gateway integrations, covering global processors like Stripe, PayPal, and Braintree alongside regional ones like bKash, Nagad, SSLCommerz, GCash, Maya, and PromptPay.

Double-entry ledger, not a transactions table. Every payment produces balanced ledger entries, not just a row in a payments table. There is an op_ledger_accounts, op_ledger_transactions, and op_ledger_entries schema that enforces balance constraints at the database level. Refunds and multi-currency conversions post atomically, guarded by mutexes, so you do not end up with a ledger that does not add up.

// Balanced ledger entries for every payment
$ledger->record([
    'debit'  => ['customer_receivable', $amount],
    'credit' => ['merchant_revenue', $amount],
]);

Offline and manual payments are first-class. A lot of self-hosted gateway projects treat bank transfers and manual MFS payments as an edge case. OwnPay has a full manual gateway system for showing bank details or QR codes, plus something I am fairly proud of: an SMS-to-payment confirmation pipeline. A companion Android app parses incoming bank or MFS SMS notifications, matches transaction IDs or amount and timeframe against a pending invoice, and confirms the checkout automatically. It authenticates over JWT with automatic key rotation and instant device revocation, so you are not stuck manually reconciling bank statements against orders.

Why I built a custom core instead of using a framework

This is the question I get most from other developers, so let me address it directly. Why not just build this on top of Laravel or Symfony?

The honest answer is that OwnPay needed a few things that off-the-shelf frameworks do not solve cleanly out of the box: strict multi-brand domain isolation at the query layer, a sandboxed plugin execution model for third-party gateway code, and a domain-specific hook engine similar to WordPress actions and filters. Bending a full framework to do all three well would have meant fighting its conventions more than leveraging them.

Going custom cost more time upfront, but it means I control the entire boot pipeline, there is no dead code from unused framework features, and the security surface is something I own end to end rather than inheriting from a dependency tree I do not fully control. When the product is literally moving money, that tradeoff felt worth it.

Installation is deliberately boring

I did not want OwnPay to require Docker, Kubernetes, or a DevOps background to run. A huge percentage of small businesses and freelancers run on cheap shared hosting or a small VPS, and that had to be a supported first-class path, not an afterthought.

Requirements are simple:

PHP 8.3 or later, with bcmath, json, mbstring, openssl, pdo_mysql, and curl
MySQL 8.0+ or MariaDB 10.6+
Apache with mod_rewrite, or Nginx, pointed at the public/ directory

The release archive is self-contained. No Composer or SSH access is required if you are on shared hosting. You upload the zip, point your domain at public/, and the installer handles the rest.

If you prefer working from source:

git clone https://github.com/own-pay/OwnPay.git
cd OwnPay
composer install --no-dev --optimize-autoloader
cp .env.example .env
# edit .env with your DB credentials and SMTP settings
mysql -u root ownpay < database/schema.sql
php database/seeds/admin.php

Point your web root to public/, and you are running your own payment gateway.

Security is not an afterthought

Anything that touches money needs to be held to a higher bar, and I have tried to treat security as an ongoing process rather than a one-time checklist. Recent work in this area included closing a gap in the webhook pipeline where a gateway's identity was not fully verified, which had opened up a potential server-side request forgery vector. Invoice PDF downloads now sanitize the output filename to prevent path traversal. Permission checks on the brand appearance and theme page were tightened so they correctly require plugin view or manage permissions instead of being reachable by anyone with general admin access.

None of that is glamorous work, but it is the work that matters most in a payment system. If you are evaluating self-hosted financial software, I would encourage you to actually read the changelog and commit history of any project you are considering, not just the marketing page. That transparency is exactly why OwnPay is open source under AGPL-3.0 in the first place. The code, the commits, and the security fixes are all public.

Extending it: gateways, hooks, and the plugin system

If you want to add a payment gateway that is not in the default 123, the plugin architecture is intentionally similar to WordPress, since that is a mental model a huge number of developers already carry around.

A gateway plugin needs:

A directory under modules/gateways/<your-gateway>/
A manifest.json describing the plugin
An adapter class implementing GatewayAdapterInterface

Addons and checkout themes follow the same hook-based extension pattern, using action and filter hooks rather than requiring changes to core files. That separation matters for anyone running a fork in production, since it means upstream updates do not stomp on your customizations.

There is also a REST API for programmatic access and HMAC-signed webhooks for real-time event notifications:

GET /api/v1/payments/op_7Xk9mN2q

{
  "event": "payment.completed",
  "amount": 4999,
  "currency": "USD"
}

Where the project is headed

OwnPay follows what I think of as a "ship when it is ready" approach rather than a fixed release calendar. Docker support is planned for an upcoming release to make local testing and containerized deployment easier. Beyond that, the roadmap is shaped heavily by what self-hosters and contributors actually ask for, since this is a community project first.

If you are building for markets where local payment rails matter as much as global ones, or if you simply do not want a percentage of every sale routed through a third party, I would genuinely like your feedback. Star the repo, open an issue, or better yet, try installing it on a spare VPS this weekend and tell me where it breaks.

Payment infrastructure should be something you own, not something you rent. That is the whole thesis behind this project, and I would love to hear what you think.