tech/sxchnge
1
0 Fork 0
Code Issues 6 Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity

Consolidate repository skills under .agents/skills #17

Merged
tech merged 3 commits from skills-16 into main 2026-09-12 10:11:37 +00:00
Conversation 0 Commits 3 Files Changed 4
+184 -34
6 changed files with 184 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit a001337bf7 - Show all commits

No files matched your search

.agents/skills/ux-design/SKILL.md
+6
View File
@@ -10,6 +10,10 @@ before reporting it complete. Rendering correctly is only one part of completion
## Establish the flow
- Prefer the simplest interface that lets users complete their task confidently.
When options meet the same need, choose fewer concepts, choices, and controls.
Add complexity only for a concrete user need; preserve essential information,
accessibility, and recovery rather than hiding them to make a screen look minimal.
- Identify the user's primary task, successful outcome, and shortest appropriate
path to that outcome before choosing layouts or controls.
- Inspect comparable product flows, components, navigation, terminology, and
@@ -95,6 +99,8 @@ performed and any gaps; do not mark applicable unmet criteria as complete.
- [ ] Are interactive elements recognizable, and can the user tell what is
happening and what will happen next?
- [ ] Are steps appropriate, with unnecessary interaction and cognitive load removed?
- [ ] Is this the simplest usable solution, with each added concept, choice, or
control serving a concrete user need?
- [ ] Does the flow follow existing product patterns and consistent terminology,
with a concrete reason for any departure?
- [ ] Can users recover from errors, with input and context preserved where appropriate?
.gitignore
+3
View File
@@ -22,3 +22,6 @@ pnpm-debug.log*
# jetbrains setting folder
.idea/
# Local editor configuration
/.vscode/
.vscode/extensions.json
Vendored
-4
View File
@@ -1,4 +0,0 @@
{
"recommendations": ["astro-build.astro-vscode"],
"unwantedRecommendations": []
}
.vscode/launch.json
Vendored
-12
View File
@@ -1,12 +0,0 @@
{
"version": "0.2.0",
"configurations": [
{
"command": "npm run dev -- --background",
"cwd": "${workspaceFolder}/website",
"name": "Development server",
"request": "launch",
"type": "node-terminal"
}
]
}
README.md
+146 -18
View File
@@ -1,43 +1,171 @@
# SXCHNGE
Product repository for the sxchnge public website, consumer frontend, and backend for frontend (BFF).
Product repository for the sxchnge public website, Flutter consumer app, reusable
packages, and planned backend for frontend (BFF).
## Current state
The consumer app includes responsive login/signup, English and Russian
localization, email verification and recovery screens, and URL-based navigation
with `go_router`. Its interface uses the shared theme's colors and typography.
**Authentication, email verification and analytics use dummy services.** No real
account or session is created, no email is delivered, and no analytics data is
transmitted. The backend is documentation only. Session/KYC access guards and
Sendico integration are not implemented.
## Repository structure
| Folder | Purpose | Status |
| --- | --- | --- |
| [`website/`](website/README.md) | Existing Astro public website, assets, brand references, and Sites configuration | Implemented |
| [`frontend/`](frontend/README.md) | Consumer application and Flutter packages | Theme, shared auth, localized app, verification and routing implemented |
| [`backend/`](backend/README.md) | Product BFF integrating with Sendico | Prepared for implementation |
| Location | Purpose |
| --- | --- |
| [`website/`](website/README.md) | Astro public website, assets, brand references and hosting configuration |
| [`frontend/app/`](frontend/app/README.md) | Flutter consumer app with a web runner |
| [`sxchnge_theme`](frontend/packages/sxchnge_theme/README.md) | Reusable light/dark themes and bundled Onest font |
| [`sxchnge_auth`](frontend/packages/sxchnge_auth/README.md) | Shared login/signup/verification contracts, providers and dummy services |
| [`sxchnge_analytics`](frontend/packages/sxchnge_analytics/README.md) | Typed journey events, recorder and bounded in-memory dummy analytics |
| [`backend/`](backend/README.md) | Planned BFF and Sendico integration boundaries |
| [`.agents/skills/`](.agents/skills) | Repository agent skills |
| [`docs/`](docs/implementation.md) | Implementation records and UX measurement contracts |
Each application owns its dependencies and deployment configuration. The frontend includes the reusable `sxchnge_theme` Flutter package; the backend currently contains documentation only.
Each application owns its dependencies and build configuration. Shared Dart and
Flutter packages can be reused by a future mobile app; mobile runners are not
currently included. Local `.vscode/` configuration is ignored.
## Website development
## Run the consumer app
Run the existing website commands from its new folder:
Requires Flutter **3.47.0 or later** with Dart **3.13.0 or later** (below Dart 4), matching
the application's package constraints, and Chrome for this run command.
```sh
cd frontend/app
flutter pub get
flutter gen-l10n
flutter run -d chrome
```
Build the web app from the same directory:
```sh
flutter build web --no-wasm-dry-run
```
Output is `frontend/app/build/web/`. To inspect that build locally, from the
repository root:
```sh
python3 -m http.server 5123 --bind 127.0.0.1 --directory frontend/app/build/web
```
Open [the local app](http://127.0.0.1:5123/). The language selector supports EN/RU
and saves the language preference. Edit translations in `frontend/app/lib/l10n/`
and regenerate with `flutter gen-l10n`; do not edit generated translations.
## Preview email verification
Signup leads to the simulated email-sent screen. Its demo confirmation button
previews completion. Direct confirmation URLs use hash routing:
| URL suffix | Preview outcome |
| --- | --- |
| `/#/verification-sent` | Request an email; a direct visit asks for the address |
| `/#/verify-email?token=demo-valid` | Simulated verification complete |
| `/#/verify-email?token=demo-expired` | Expired link with recovery |
| `/#/verify-email?token=demo-internal` | Internal error with primary retry |
| `/#/verify-email` or an unknown token | Invalid confirmation |
Signup email stays transient and is excluded from serialized browser history.
The sent recipient is read-only until **Change email** is selected. All current
routes are public; these previews do not establish authentication or authorization.
## Analytics and PostHog preparation
The app accepts an injectable `AnalyticsService` and defaults to
`DummyAnalyticsService`. It keeps up to 500 semantic events in memory and never
captures form contents, confirmation tokens or raw errors. Events cover submitted
auth journeys, service outcomes, retries and known abandonment; simulated outcomes
are distinguished from real conversion.
A future PostHog adapter can replace the sink. No PostHog SDK or credentials are
configured. Read the [auth journey contract](docs/ux/auth-journeys.md) for event
properties, attempt and timing rules, metric definitions, privacy requirements,
and cross-device/termination measurement limitations.
## Run the public website
Requires Node.js **22.12.0 or later** and npm, matching `website/package.json`.
From the repository root:
```sh
cd website
npm ci
npm run dev -- --background --host 127.0.0.1
```
Manage the background server from `website/`:
```sh
npm exec astro dev status
npm exec astro dev logs
npm exec astro dev stop
```
Website builds go to `website/dist/`. Use `website/` as the working directory
for hosting tools; the existing hosting identity lives in
`website/.openai/hosting.json`. The website and consumer app are separate builds.
## Validate changes
From the repository root, run all shared-package and app tests:
```sh
make test-frontend
```
From each changed Flutter package, run formatting and analysis. For example:
```sh
cd frontend/app
dart format --output=none --set-exit-if-changed lib test
flutter analyze
```
Validate the website independently:
```sh
cd website
npm run test
npm run check
npm run build
```
From `website/`, manage the background server with `npm exec astro dev status`, `npm exec astro dev logs`, and `npm exec astro dev stop`. Build output is `website/dist/`. Use `website/` as the working directory for website hosting tools; its existing Sites identity is preserved in `website/.openai/hosting.json`.
Rendering and passing tests do not alone establish UX completion. Review
usability, accessibility and journey measurement under the repository's UX rules.
## Product boundaries
The intended integration is: consumer frontend → sxchnge BFF → supported Sendico API.
The intended integration is: **consumer app → sxchnge BFF → supported Sendico API**.
- sxchnge owns consumer registration and sessions, the onboarding and exchange experience, and mapping authenticated consumers to stable organization-scoped Sendico customer references.
- Sendico remains authoritative for payment execution, KYC records and verification, policy decisions, and limit enforcement.
- The sxchnge organization, backend integration principal, and individual customer references are distinct identities. Consumers must not share the integration account's customer identity.
- The BFF should use a supported API contract rather than copying Sendico's existing BFF or depending on its local internal modules.
- sxchnge will own consumer registration/sessions, onboarding and exchange UX,
and mappings to stable, organization-scoped Sendico customer references.
- Sendico remains authoritative for payment execution, KYC records and
verification, policy decisions and limit enforcement.
- The sxchnge organization, backend integration principal and individual customer
references are distinct identities. Consumers must not share the integration
account's customer identity.
- The BFF should use a supported API contract rather than copying Sendico's BFF
or depending on its local internal modules. Integration credentials belong in
the backend.
Before implementing the product, define one complete transaction flow and agree on the Sendico customer, KYC, eligibility/limits, and customer-scoped payment contracts. These are intended boundaries, not claims that the required Sendico operations already exist.
Before backend integration, agree on the customer, KYC, eligibility/limits and
customer-scoped payment contracts for one complete transaction flow. These are
intended boundaries, not claims that the required operations already exist.
## Delivery record
## Contribution workflow
See [the implementation record](docs/implementation.md) for delivered scope, task mapping, validation, and PR dependencies. Repository workflow skills and frontend guidelines are stored locally under `.agents/skills/` and `frontend/AGENTS.md`.
Follow [`AGENTS.md`](AGENTS.md) and the applicable scoped guidelines, including
[`frontend/AGENTS.md`](frontend/AGENTS.md). Repository skills belong under
[`.agents/skills/`](.agents/skills).
Implementation work uses a Gitea task and linked branch, validation, commits,
a push and a PR. Merge only when authorized. Record scope, validation and known
limitations in the task and [implementation record](docs/implementation.md).
docs/implementation.md
+29
View File
@@ -133,3 +133,32 @@ byte-for-byte, checks all four skill paths and updated UX links, and runs
`git diff --check`. No runtime tests are needed for this move.
Delivery: [PR #17](https://git.sendico.io/tech/sxchnge/pulls/17), branch `skills-16`.
## Editor configuration cleanup
Task [#14](https://git.sendico.io/tech/sxchnge/issues/14) removes the root VS Code
extension recommendations and launch configuration. Root `.vscode/` is ignored
so personal editor configuration stays local. Development uses the CLI commands
in the README. Validation: no tracked root `.vscode` files, ignore rule verified,
and diff whitespace check passed. Runtime tests are unnecessary for this change.
Delivery: [PR #15](https://git.sendico.io/tech/sxchnge/pulls/15), branch `editor-14`.
## Root README refresh
Task [#18](https://git.sendico.io/tech/sxchnge/issues/18), delivered in
[PR #19](https://git.sendico.io/tech/sxchnge/pulls/19) on `docs-18`, documents
current packages, app/website commands, verification previews, analytics limits,
skill location and contribution workflow. Local links and diff checks pass;
commands and prerequisites were checked against repository configuration.
Documentation only; no runtime tests were run.
## UX simplicity preference
Task [#26](https://git.sendico.io/tech/sxchnge/issues/26), delivered in
[PR #27](https://git.sendico.io/tech/sxchnge/pulls/27) on `skills-26`, makes
simplicity an explicit preference in the UX Design skill and its review checklist.
Prefer fewer concepts, choices, and controls when they serve the same need; retain
essential information, accessibility, and recovery. Documentation only.
Validation: skill-creator `quick_validate.py` passed in an isolated environment
with PyYAML (the system Python lacked it); `git diff --check` passed. No runtime
tests were needed. The PR is not merged.